TABLE OF CONTENTS gadget.library/gadAllocGadgetA gadget.library/gadAllocIntuiText gadget.library/gadFilterMessage gadget.library/gadFreeGadget gadget.library/gadFreeGadgetList gadget.library/gadFreeIntuiText gadget.library/gadGetGadgetAttr gadget.library/gadSetGadgetAttrsA gadget.library/gadAllocGadgetA gadget.library/gadAllocGadgetA NAME gadAllocGadgetA -- Allocate and initialize a gadget. gadAllocGadget -- Varargs stub for gadAllocGadgetA(). SYNOPSIS gad = gadAllocGadgetA(kind, taglist) D0 D0 A0 struct Gadget *gadAllocGadgetA(ULONG, struct TagItem *); gad = gadAllocGadget(kind, firsttag, ...) struct Gadget *gadAllocGadget(ULONG, Tag, ...); FUNCTION gadAllocGadgetA() allocates and initializes a new gadget of the specified kind with the supplied tags. This function may create more than one gadget (e.g. GAD_SCROLLER_KIND). So you have to specify the GA_Previous tag to get the first gadget generated. You can count the number of gadgets generated, but this number may change during execution time. INPUTS kind - to indicate what kind of gadget is to be created. taglist - pointer to a TagItem list. TAGS GAD_ARROW_KIND (arrow gadget): GA_Left - (SHORT) Left edge of gadget. GA_Top - (SHORT) Top edge of gadget. GA_RelRight - (SHORT) Left edge of gadget. The real position will be Window->Width + GA_RelRight. So this value should be negative. GA_RelBottom - (SHORT) Top edge of gadget. The real position will be Window->Height + GA_RelBottom. So this value should be negative. GA_Width - (SHORT) This gadget has a fixed width. If you specify this tag the gadget will be centered horizontal on the supplied value. GA_Height - (SHORT) This gadget has a fixed height. If you specify this tag the gadget will be centered vertical on the supplied value. GA_Previous - (struct Gadget **) Pointer to a gadget pointer, may be NULL (default). The gadget pointer will be initialized to the first gadget generated by the gadAllocGadgetA call. Note that possibly this call will generate more than one gadget. So you MUST specify this tag if you want to add the gadget(s) to a linked list (e.g. NewWindow.FirstGadget). GAD_ShortCut - (UBYTE) Shortcut for the gadget. You can specify all ascii- codes as shortcuts. Characters 'a' - 'z' are equivalent to 'A' - 'Z' (case is ignored). Special characters are 13 (RETURN) and 27 (ESCAPE). If you specify 13 the text in the gadget (if any) will be displayed in boldface. (Defaults to 0, no shortcut). GAD_CallBack - (void (*function)(gad, win, req, special, class)) Function which will be called if the user acts with the gadget. The parameters are pushed on the stack. INPUTS gad - (struct Gadget *) the gadget itself. win - (struct Window *) window which contains the gadget. req - (struct Requester *) not yet supported. special - (APTR) pointer to a special, kind dependend structure which contains more information about the gadget status. class - (ULONG) message class which has caused the functioncall. Values can be one of IDCMP_GADGETUP, IDCMP_GADGETDOWN, IDCMP_INTUITICKS or IDCMP_MOUSEMOVE. The gadget.library never uses register a4. So if your compiler uses a4 as global index pointer (like AZTEC C) you don't have to worry about register a4. (Defaults to NULL, no callback function). GA_UserData - (APTR) Pointer to user data, may be NULL (default). GA_Disabled - (BOOL) Set to TRUE to disable gadget, FALSE otherwise (defaults to FALSE). GA_RelVerify - (BOOL) If set to TRUE the callback function for the gadget is called (if installed) after the user has clicked in the gadget and has released the button on it. Set to FALSE to disable the callback. (Defaults to TRUE). GA_Immediate - (BOOL) If set to TRUE the callback function of the gadget is called (if installed) immediatly after the user clicked in the gadget. (Defaults to FALSE). If you set both GA_RelVerify and GA_Immediate to TRUE the call- back function is also called on INTUITICK messages. This means that the callback function will be called while the user has pressed the button over the gadget. GA_LeftBorder - (BOOL) If set to TRUE the gadget will be part of the left window border. (Defaults to FALSE). GA_RightBorder - (BOOL) If set to TRUE the gadget will be part of the right window border. (Defaults to FALSE). GA_TopBorder - (BOOL) If set to TRUE the gadget will be part of the top window border. (Defaults to FALSE). GA_BottomBorder- (BOOL) If set to TRUE the gadget will be part of the bottom window border. (Defaults to FALSE). GA_GZZGadget - (BOOL) If set to TRUE the gadget will become a GimmeZeroZero gadget (see intuition.library). (Defaults to FALSE). GADAR_Which - (LEFTIMAGE | RIGHTIMAGE | UPIMAGE | DOWNIMAGE) Specifies the image which will be displayed in the gadget. GAD_BEVELBOX_KIND (bevelbox without functionality): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GA_Width - (SHORT) Width of the bevelbox. GA_Height - (SHORT) Height of the bevelbox. GA_Text - (BYTE *) Text which will be displayed in the top border of the bevelbox. May be NULL (default) for a null-string. The string will be referenced. GADBB_Recessed - (BOOL) If TRUE the bevelbox will have a recessed border, otherwise it will have a raised border. (Defaults to TRUE). GAD_BOOL_KIND (raw bool gadget): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GA_Width - (SHORT) Width of gadget. GA_Height - (SHORT) Height of gadget. GA_RelWidth - Width of gadget. The real width will be Window->Width + GA_RelWidth. So this value should be negative. GA_RelHeight - Height of gadget. The real height will be Window->Height + GA_RelHeight. So this value should be negative. GA_Selected - (BOOL) Initial state of the bool gadget. (Defaults to FALSE). GA_Text - (BYTE *) Text which will be displayed in the gadget. May be NULL (default). The string will be copied. If you use the symbol '_' in the textstring, the character that follows this symbol will be underscored and the shortcut for the gadget will be set to this character. Note that this overrides the value of the GAD_ShortCut tag. GA_IntuiText - (struct IntuiText *) Pointer to IntuiText structure which will be stored in gadget->GadgetText. May be NULL (default). GA_Text will be ignored. GA_Border - (struct Border *) Pointer to Border structure which will be stored in gadget->GadgetRender. May be NULL (default). GA_Image - (struct Image *) Pointer to Image structure which will be stored in gadget->GadgetRender. May be NULL (default). Also GFLG_GADGIMAGE will be set in gadget->Flags. GA_SelectRender- (APTR) Pointer which will be stored in gadget->GadgetRender. May be NULL (default). Also GFLG_GADGHIMAGE will be set in gadget->Flags. GA_Highlight - (GFLG_GADGHCOMP | GFLG_GADGHBOX | GFLG_GADGHNONE) Specifies the highlight method. (Defaults to GFLG_GADGHCOMP or GFLG_GADGHIMAGE if GA_SelectRender is supplied). GA_ToggleSelect- (BOOL) Set to TRUE if you want a toggleselect gadget. (Defaults to FALSE). GAD_BUTTON_KIND (action buttons): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_Text (see GAD_BOOL_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GA_Width - (SHORT) Width of gadget. (Defaults to stringlen of text). GA_Height - (SHORT) Height of gadget. (Defaults to 14). GAD_CHECKBOX_KIND (on/off items): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Width - (see GAD_ARROW_KIND) GA_Height - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GA_Selected - (BOOL) Initial state of gadget, defaults to FALSE. GA_Text - (BYTE *) Text which will be displayed to the left of the gadget. May be NULL (default). The string will by copied. If you use the symbol '_' in the textstring the character that follows this symbol will be underscored and the shortcut for the gadget will be set to this character. This will override the value of the GAD_ShortCut tag. GAD_CYCLE_KIND (multiple state selections): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_Text - (see GAD_CHECKBOX_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) The callback function will get a pointer to the following structure as the special parameter: struct gadCycleInfo { USHORT active; /* see GADCYC_Active */ BYTE **labels; /* see GADCYC_Labels */ }; GA_Width - (SHORT) Width of gadget. (Defaults to largest stringlen of the initial labelstringarray). GA_Height - (SHORT) Height of gadget. (Defaults to 14). GADCYC_Labels - (BYTE **) Pointer to NULL-terminated array of strings that are the choices offered by the cycle gadget. May be NULL (default) for an empty cycler. GADCYC_Active - (USHORT) The ordinal number (counting from zero) of the initially active choice of the cycle gadget. (Defaults to zero). GAD_GETFILE_KIND (bool gadget with getfile symbol, but without filerequester): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Width - (see GAD_ARROW_KIND) GA_Height - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_INTEGER_KIND (numeric entry): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_Text - (see GAD_CHECKBOX_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GA_Width - (SHORT) Width of the gadget. (Defaults to stringlen of a string with maxchars-1 characters). GA_Height - (see GAD_ARROW_KIND) GA_TabCycle - (BOOL) Set to TRUE so that pressing or will activate the next or previous string/integer gadget. (Defaults to TRUE). GADSTR_Min - (LONG) Minimum value that can be entered (defaults to -2147483647). See also GADSTR_Max. GADSTR_Max - (LONG) Maximum value that can be entered (defaults to 2147483647). The values of GADSTR_Min and GADSTR_Max are only used to calculate the number of digits the stringgadget must have. There is no guarantee that the user can't input a number out of the given range. GADSTR_MaxChars- (SHORT) The maximum number of characters that the gadget is to hold (incl. null-byte). Minimum value is 2, maximum value is 1000. This tag will override the meaning of the GADSTR_Min and GADSTR_Max tags. GADSTR_Justification - (GACT_STRINGCENTER | GACT_STRINGLEFT | GACT_STRINGRIGHT) Controls the justification of the contents of the gadget. (Defaults to GACT_STRINGCENTER). GADSTR_LongVal - (LONG) The initial contents of the gadget. (Defaults to zero). GADSTR_BufferPos- (USHORT) Position of the Cursor in the editbuffer. (Defaults to zero). GADSTR_DispPos - (USHORT) The ordinal number (counting from zero) of the first displayed character. (Defaults to zero). GADSTR_EndGadget: (BOOL) If set to TRUE pressing RETURN while editing the contents of the gadget will result in activating the gadget with shortcut RETURN (13). (Defaults to FALSE). GAD_LISTVIEW_KIND (scrolling list): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) The callback function will be called whenever the user selects a listitem. The function will get a pointer to the following structure as the special parameter: struct gadListviewInfo { USHORT total; /* total number of items */ USHORT visible; /* number visible */ USHORT top; /* see GADLV_Top */ USHORT selected; /* see GADLV_Selected */ struct List *list; /* see GADLV_Labels */ }; GA_Width - (SHORT) Width of gadget. GA_Height (SHORT) Height of gadget, without eventual show-selected-gadget. GADLV_ShowSelected- (struct Gadget *) NULL to have the currently selected item displayed beneath the listview, or pointer to an already-created GAD_STRING_KIND gadget to have an editable display of the currently selected item. (Default is no show- selected gadget). GADLV_Labels - (struct List *) List of labels whose ln_Name fields are to be displayed in the listview. May be NULL (default). GADLV_Top - (USHORT) Ordinal number (counting from zero) of top item visible in the listview (defaults to zero). GADLV_Selected - (USHORT) Ordinal number (counting from zero) of currently selected item, or ~0 to have no current selection. (Defaults to ~0). GAD_MX_KIND (mutually exclusive, radio buttons): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) The callback function will be called whenever the user selects a radiobutton. The function will get a pointer to the following structure as the special parameter: struct gadMXInfo { USHORT active; /* see GADMX_Active */ }; GADMX_Labels - (BYTE **) Pointer to a NULL-terminated array of strings which are to be the labels left of each choice in a set of mutually exclusive gadgets. Use '_' in the strings to set the shortcuts for the radiobutton gadgets. May be NULL (default) for no radiobuttons. GADMX_Active (USHORT) The ordinal number (counting from zero) of the initially active choice of an mxgadget. (Defaults to zero). GAD_PALETTE_KIND (color selection): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_Text - (see GAD_CHECKBOX_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) Shortcuts only work when you specify the GADPA_IndicatorWidth tag. GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) The callback function will be called whenever the user selects a colorgadget. The function will get a pointer to the following structure as the special parameter: struct gadPaletteInfo { USHORT color; /* see GADPA_Color */ USHORT coloroffset; /* see GADPA_ColorOffset */ USHORT depth; /* see GADPA_Depth */ }; GA_Width - (SHORT) Width of gadget, without eventual indicator-gadget. GA_Height (SHORT) Height of gadget. GADPA_Depth - (USHORT) Number of bitplanes in the palette. (Defaults to 1). Minimum is 1, maximum is 8. GADPA_ColorOffset - (USHORT) First color to use in palette. (Defaults to zero). GADPA_IndicatorWidth - (SHORT) The desired width of the current-color indicator, if you want one to the left of the palette. (Defaults to zero, no indicator-gadget). GADPA_Color - (USHORT) Initially selected color of the palette. (Defaults to the value of GADPA_ColorOffset). GAD_RADIOBUTTON_KIND (single radiobutton): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Width - (see GAD_ARROW_KIND) GA_Height - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_Text - (see GAD_CHECKBOX_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Selected - (see GAD_CHECKBOX_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_SCROLLER_KIND (for scrolling through areas or lists): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) The callback function will be called whenever the user selects an arrow gadget or plays with the prop gadget. The function will get a pointer to the following structure as the special parameter: struct gadScrollerInfo { USHORT total; /* see GADSC_Total */ USHORT visible; /* see GADSC_Visible */ USHORT top; /* see GADSC_Top */ }; GA_Width - (SHORT) Width of gadget including the arrows. (Defaults to 18 for vertical scrollers). GA_Height - (SHORT) Height of gadget including the arrows. (Defaults to 10 for horizontal scrollers). GA_RelWidth - (SHORT) Width of gadget including the arrows. The real width will be Window->Width + GA_RelWidth, so this value should be negative. If you use this tag the gadget will be borderless. (But looks good in OS 2.0 window borders). GA_RelHeight - (SHORT) Height of gadget including the arrows. The real height will be Window->Height + GA_RelHeight, so this value should be negative. If you use this tag the gadget will be borderless. (But looks good in OS 2.0 window borders). GADSC_Freedom - (FREEVERT | FREEHORIZ) Whether scroller is horizontal or vertical. GADSC_Jump - (USHORT) Value which the scroller should jump if an arrowgadget has been selected. (Defaults to 1). GADSC_NewLook - (BOOL) Use the new propgadget look (OS 2.0 only). (Defaults to FALSE). GADSC_Total - (USHORT) Total in area scroller represents. (Defaults to 1). GADSC_Visible - (USHORT) Number visible in scroller. (Defaults to 1). GADSC_Top - (USHORT) Top visible in area scroller represents. (Defaults to zero). GAD_STRING_KIND (text-entry): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Width - (see GAD_INTEGER_KIND) GA_Height - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_Text - (see GAD_CHECKBOX_KIND) GAD_ShortCut - (see GAD_ARROW_KIND) GAD_CallBack - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_TabCycle - (see GAD_INTEGER_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_RelVerify - (see GAD_ARROW_KIND) GA_Immediate - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GADSTR_Justification - (see GAD_INTEGER_KIND) GADSTR_BufferPos- (see GAD_INTEGER_KIND) GADSTR_DispPos - (see GAD_INTEGER_KIND) GADSTR_EndGadget- (see GAD_INTEGER_KIND) GADSTR_MaxChars- (SHORT) The maximum number of characters that the gadget is to hold (incl. null-byte). Minimum value is 2, maximum value is 1000. (Defaults to 128). GADSTR_TextVal - (BYTE *) The initial contents of the stringgadget, or NULL (default) if string is to start empty. GAD_TEXT_KIND (read-only text): GA_Left - (see GAD_ARROW_KIND) GA_Top - (see GAD_ARROW_KIND) GA_RelRight - (see GAD_ARROW_KIND) GA_RelBottom - (see GAD_ARROW_KIND) GA_Previous - (see GAD_ARROW_KIND) GA_UserData - (see GAD_ARROW_KIND) GA_Disabled - (see GAD_ARROW_KIND) GA_LeftBorder - (see GAD_ARROW_KIND) GA_RightBorder - (see GAD_ARROW_KIND) GA_TopBorder - (see GAD_ARROW_KIND) GA_BottomBorder- (see GAD_ARROW_KIND) GA_GZZGadget - (see GAD_ARROW_KIND) GA_Width - (SHORT) Width of gadget. (Defaults to stringlen of text). GA_Height - (SHORT) Height of gadget. (Defaults to 14). GA_Text - (BYTE *) Text which will be displayed in the gadget, or NULL (default) to have an empty string. The string will be copied. If the string is too long, it will be truncated. No shortcut support. GA_Border - (BOOL) If TRUE, this flag asks for a recessed border to be placed around the gadget. (Defaults to TRUE). RESULT gad - pointer to the new gadget, or NULL if the allocation failed (No memory). EXAMPLE { struct NewWindow nw = { ... }; struct Gadget *gad; if((gad = gadAllocGadget(GAD_BOOL_KIND, /* Allocate raw bool */ GA_RelRight, -17L, /* in right window */ GA_Top, 11L, /* border */ GA_Width, 18L, GA_Height, 10L, GA_Text, "R", GA_RightBorder, 1L, GA_Previous, &nw.FirstGadget, GAD_CallBack, myRefreshWindow, TAG_DONE)) && (gad = gadAllocGadget(GAD_SCROLLER_KIND, /* attach scroller */ GA_Left, 0L, /* in bottom window */ GA_RelBottom, -9L, /* border */ GA_RelWidth, -18L, GA_BottomBorder, 1L, GA_Previous, &gad->NextGadget, GAD_CallBack, myScrollX, GADSC_Freedom, (LONG)FREEHORIZ, GADSC_NewLook, 1L, TAG_DONE)) && (gad = gadAllocGadget(GAD_SCROLLER_KIND, /* attach scroller */ GA_RelRight, -17L, /* in right window- */ GA_Top, 11L+10L-2L, /* border */ GA_RelHeight, -11L-10L-10L+2L, GA_RightBorder, 1L, GA_Previous, &gad->NextGadget, GAD_CallBack, myScrollY, GADSC_Freedom, (LONG)FREEVERT, GADSC_NewLook, 1L, TAG_DONE)) && (w = OpenWindow(&neww))) { /* Let the user play with the gadgets and wait on closewindow (see example in gadFilterMessage) */ CloseWindow(w); } else bomb("Can't allocate gadgets or open window!"); FreeGadgetList(&nw.FirstGadget); /* free all gadgets */ } This example will open a window with two scrollers in the right and bottom border and a "R" (refresh) gadget in the right border above the scroller. NOTES Do not specify tags for a gadget which are not in the gadget's taglist or the reslult will be undefined. BUGS Under OS 1.3 while an integer/string gadget is active you don't have the shortcut support. You can't mix gadget.library gadgets with your own gadgets or gadtools gadgets. SEE ALSO gadFreeGadget(), gadFreeGadgetList(), gadSetGadgetAttrs(). gadget.library/gadAllocIntuiText gadget.library/gadAllocIntuiText NAME gadAllocIntuiText -- Easy way to allocate and initialize an IntuiText- structure. SYNOPSIS it = gadAllocIntuiText(fpen, bpen, dmode, x, y, textattr, text, nextit) D0 D0 D1 D2 D3 A0 A1 A2 A3 struct IntuiText *gadAllocIntuiText(SHORT, SHORT, SHORT, SHORT, SHORT, struct TextAttr *, BYTE *, struct IntuiText *) FUNCTION gadAllocIntuiText() allocates and initializes a new IntuiText structure. The structure is created based on the supplied parameters. INPUTS fpen - Front pen. bpen - Back pen. dmode - Draw mode (JAM1, JAM2, ...). x - Left edge. y - Top edge. textattr - Font, may be NULL. text - String to display, may be NULL. The string will be referenced. nextit - Pointer to next intuitext, may be NULL. RESULT it - pointer to the new IntuiText structure, or NULL if the allocation failed (No memory). EXAMPLE NOTES BUGS SEE ALSO gadFreeIntuiText(). gadget.library/gadFilterMessage gadget.library/gadFilterMessage NAME gadFilterMessage -- Filter an IntuiMessage through the eventhandler. SYNOPSIS message_has_been_processed = gadFilterMessage(imsg, amigakeys) D0 A0 D0 SHORT gadFilterMessage(struct IntuiMessage *, ULONG) FUNCTION gadFilterMessage() examines the supplied IntuiMessage if it is an event to act on. If true the actions will be done immediatly. This can be internal operations as well as to call callback functions which are supplied with the GAD_CallBack tag at creation time of the gadgets. After the actions took place the function will return TRUE to indicate that the caller don't need to act on the message any more. Otherwise (no action took place) it returns FALSE and the caller has to determine what to do. In both cases the caller has to reply the message. INPUTS imsg - an IntuiMessage you obtained from a window's userport. amigakeys- flag to indicate if the user must hold down an amigakey (left amiga, or right amiga) to have shortcut support. If set to TRUE the shortcuts only work while pressing an amigakey. This is usefull for programs that want to get RAWKEY messages but also want shortcuts for their gadgets. Note: You don't need to set amigakeys to TRUE while a integer/string gadget is active, this is handled internally. RESULT message_has_been_processed - TRUE if the message has been processed by the internal eventhandler, or FALSE if the message must be processed by the caller. EXAMPLE { struct MsgPort *msgport = ... struct Message *msg; struct IntuiMessage imsg; for(;;) { if(!(msg = GetMsg(msgport))) { Wait(1L << msgport->mp_SigBit); continue; } /* copy message and reply it (safe way to handle messages) */ imsg = *(struct IntuiMessage *)&msg; ReplyMsg(msg); if(!gadFilterMessage(&imsg, FALSE)) /* message for me? */ { switch(imsg.Class) { case CLOSEWINDOW: ... ... } } } } NOTES BUGS SEE ALSO gadget.library/gadFreeGadget gadget.library/gadFreeGadget NAME gadFreeGadget -- Free a gadget. SYNOPSIS gadFreeGadget(gad) A0 VOID gadFreeGadget(struct Gadget *); FUNCTION Frees all memory that was allocated by gadAllocGadgetA() for the supplied gadget. This function will return safely with no action if it receives a NULL parameter. INPUTS gad - pointer to gadget to be freed (may be NULL). RESULT none EXAMPLE NOTES BUGS SEE ALSO gadAllocGadgetA(), gadFreeGadgetList(). gadget.library/gadFreeGadgetList gadget.library/gadFreeGadgetList NAME gadFreeGadgetList -- Free a linked list of gadgets. SYNOPSIS gadFreeGadgetList(glist) A0 VOID gadFreeGadgetList(struct Gadget *); FUNCTION Frees any gadgets found on the linked list of gadgets beginning with the specified one. Frees all the memory that was allocated by gadAllocGadgetA(). This function will return safely with no action if it receives a NULL parameter. INPUTS glist - pointer to first gadget in list to be freed (may be NULL). RESULT none EXAMPLE NOTES BUGS SEE ALSO gadAllocGadgetA(), gadFreeGadget() gadget.library/gadFreeIntuiText gadget.library/gadFreeIntuiText NAME gadFreeIntuiText -- Free a IntuiText structure. SYNOPSIS gadFreeIntuiText(it) A0 VOID gadFreeIntuiText(struct IntuiText *); FUNCTION gadFreeIntuiText() returns the memory of the specified IntuiText structure that was allocated by gadAllocIntuiText. It is save to call this function with a NULL parameter. INPUTS it - Pointer to an IntuiText structure that was obtained by calling gadAllocIntuiText(), or NULL to do nothing. RESULT None. EXAMPLE NOTES BUGS SEE ALSO gadAllocIntuiText(). gadget.library/gadGetGadgetAttr gadget.library/gadGetGadgetAttr NAME gadGetGadgetAttr -- Get an attribute value of a gadget. SYNOPSIS result = gadGetGadgetAttr(tag, gad, storage) D0 D0 A0 A1 ULONG gadGetGadgetAttr(ULONG, struct Gadget *, ULONG *) FUNCTION Get the attribute value of the specified gadget and the specified tag. INPUTS tag - to specifiy the attribute. gad - pointer to the gadget. storage - pointer to ULONG where the value will be stored. The storage MUST ALWAYS have space for an ULONG value. TAGS GAD_BOOL_KIND: GA_Selected - (BOOL) Current state of boolgadget, usefull for toggleselect gadgets. GAD_CHECKBOX_KIND (on/off items): GA_Selected - (BOOL) Current state of gadget. GAD_CYCLE_KIND (multiple state selections): GADCYC_Active - (USHORT) The ordinal number (counting from zero) of the active choice of the cycle gadget. GADCYC_Labels - (BYTE **) Pointer to NULL-terminated array of strings that are the choices offered by the cycle gadget. GAD_INTEGER_KIND GADSTR_BufferPos- (SHORT) Cursor position (counting from zero) in the string buffer. GADSTR_DispPos - (SHORT) Ordinal number (counting from zero) of the first visible character in the string buffer. GADSTR_MaxChars- (SHORT) Size of string buffer, incl. null-byte. GADSTR_DispCount- (SHORT) Number of whole characters visible in container. GADSTR_LongVal - (LONG) Current value of the integer gadget. GAD_LISTVIEW_KIND: GADLV_Top - (USHORT) Top item visible in the listview. GADLV_Labels - (struct List *) List of labels. GADLV_Selected - (USHORT) Ordinal number of currently selected item, or ~0 if no item has been selected. GAD_MX_KIND: GADMX_Active - (USHORT) The ordinal number (counting from zero) of the current active choice. GAD_PALETTE_KIND: GADPA_Color - (USHORT) Current selected color of the palette. GAD_RADIOBUTTON_KIND: GA_Selected - (BOOL) Current state of gadget. GAD_SCROLLER_KIND: GADSC_Jump - (USHORT) Value which the scroller jumps if an arrowgadget has been selected. GADSC_Total - (USHORT) Total in area scroller represents. GADSC_Visible - (USHORT) Number visible in scroller. GADSC_Top - (USHORT) Top visible in area scroller represents. GAD_STRING_KIND: GADSTR_BufferPos- (SHORT) Current cursor position (counting from zero) in the string buffer. GADSTR_DispPos - (SHORT) Ordinal number (counting from zero) of the first visible character in the string buffer. GADSTR_MaxChars- (SHORT) Size of string buffer, incl. NULL-byte. GADSTR_DispCount- (SHORT) Number of whole characters visible in container. GADSTR_TextVal - (BYTE *) The current contents of the string gadget. GAD_TEXT_KIND (read-only text): GA_Text - (BYTE *) Text which is displayed in the gadget. RESULT TRUE if the attribute has been found and the storage pointer was not NULL. FALSE otherwise. EXAMPLE NOTES BUGS SEE ALSO gadSetGadgetAttrs(). gadget.library/gadSetGadgetAttrsA gadget.library/gadSetGadgetAttrsA NAME gadSetGadgetAttrsA -- Change the attributes of a gadget. gadSetGadgetAttrs -- Varargs stub for gadSetGadgetAttrsA(). SYNOPSIS need_refresh = gadSetGadgetAttrsA(gad, win, req, taglist) D0 A0 A1 A2 A3 ULONG gadSetGadgetAttrsA(struct Gadget *, struct Window *, struct Requester *, struct TagItem *); need_refresh = gadSetGadgetAttrs(gad, win, req, firsttag, ...) ULONG gadSetGadgetAttrs(struct Gadget *, struct Window *, struct Requester *, Tag, ...); FUNCTION Change the attributes of the specified gadget, according to the attributes chosen in the tag list. INPUTS gad - Pointer to the gadget in question. win - Pointer to the window containing the gadget. req - Pointer to the requester containing the gadget, or NULL if not in a requester. (Not yet implemented, use NULL). taglist - Pointer to TagItem list. TAGS GAD_ARROW_KIND: GA_Disabled - (BOOL) Set to TRUE to disable gadget, FALSE otherwise. GAD_BOOL_KIND: GA_Disabled - (see GAD_ARROW_KIND) GA_Selected - (BOOL) State of a toggleselect bool gadget. GAD_BUTTON_KIND: GA_Disabled - (see GAD_ARROW_KIND) GAD_CHECKBOX_KIND: GA_Disabled - (see GAD_ARROW_KIND) GA_Selected - (BOOL) State of the gadget. GAD_CYCLE_KIND: GA_Disabled - (see GAD_ARROW_KIND) GADCYC_Labels - (BYTE **) Pointer to NULL-terminated array of strings which are the choices offered by the cycle gadget. The gadget will not resize. GADCYC_Active - (USHORT) The ordinal number (counting from zero) of the active choice of the cycle gadget. GAD_GETFILE_KIND: GA_Disabled - (see GAD_ARROW_KIND) GAD_INTEGER_KIND (numeric entry): GA_Disabled - (see GAD_ARROW_KIND) GADSTR_LongVal - (LONG) The contents of the gadget. GADSTR_BufferPos- (USHORT) Position of the Cursor in the edit buffer. GADSTR_DispPos - (USHORT) The ordinal number (counting from zero) of the first character to display. GADSTR_EndGadget: (BOOL) If set to TRUE pressing RETURN while editing the contents of the gadget will result in activating the gadget with shortcut RETURN (13). GAD_LISTVIEW_KIND: GA_Disabled - (see GAD_ARROW_KIND) GADLV_Labels - (struct List *) List of labels whose ln_Name fields are to be displayed in the listview (may be NULL). You don't need to detach your list before modifying it. Just call this function to update the display after you made all changes. GADLV_Top - (USHORT) Top item visible in the listview. GADLV_Selected - (USHORT) Ordinal number (counting from zero) of currently selected item, or ~0 to have no current selection. GAD_MX_KIND: GA_Disabled - (see GAD_ARROW_KIND) GADMX_Active - (USHORT) The ordinal number (counting from zero) of the active choice of the mxgadget. GAD_PALETTE_KIND: GA_Disabled - (see GAD_ARROW_KIND) GADPA_Color - (USHORT) Actually selected color of the palette. GAD_RADIOBUTTON_KIND: GA_Disabled - (see GAD_ARROW_KIND) GA_Selected - (BOOL) State of gadget. GAD_SCROLLER_KIND: GA_Disabled - (see GAD_ARROW_KIND) GADSC_Jump - (USHORT) Value which scroller should jump if an arrowgadget has been selected. GADSC_Total - (USHORT) Total in area scroller represents. GADSC_Visible - (USHORT) Number visible in scroller. GADSC_Top - (USHORT) Top visible in area scroller represents. GAD_STRING_KIND: GA_Disabled - (see GAD_ARROW_KIND) GADSTR_BufferPos- (see GAD_INTEGER_KIND) GADSTR_DispPos - (see GAD_INTEGER_KIND) GADSTR_EndGadget- (see GAD_INTEGER_KIND) GADSTR_TextVal - (BYTE *) The actual contents of the string gadget, or NULL for an empty string. GAD_TEXT_KIND (read-only text): GA_Disabled - (see GAD_ARROW_KIND) GA_Text - (BYTE *) Text which will be displayed in the gadget, or NULL to have an empty string. The string will be copied. If the string is too long, it will be truncated. RESULT TRUE if the gadget has to be refreshed, FALSE otherwise. If you specify a non-NULL window parameter the result will always be FALSE. EXAMPLE NOTES req must currently be NULL. Gadgets are not supported in requesters. This field may allow such support at a future date. Do not specify tags for a gadget which are not in the gadget's setattrs- taglist or the reslult will be undefined. BUGS SEE ALSO