@DATABASE AmigaMail @NODE MAIN "IV-125: Features of V39 GadTools" @TOC "Table_of_Contents/IV" Features of V39 GadTools by Mark Ricci The V39 GadTools library has been upgraded with new features and capabilities that support the enhanced graphic capabilities of the AA chipset. Other improvements include support for IDCMP_GADGETHELP events, more support for IDCMP_GADGETUP events, scalable imagery and a new function, GT_GetGadgetAttrs(), to obtain the values of certain gadget attributes. This article assumes you are familiar with the previous version of the GadTools library. If not, you should refer to the ``GadTools Library'' chapter of the Amiga ROM Kernel Reference Manual: Libraries for an in-depth explanation of GadTools. You should also refer to the GadTools Autodoc for complete explanations of the GadTools functions. All tags and constants referenced in this article are defined in and . The NewLook Menus For V37, Intuition received a facelift. V37 introduced the ``NewLook'' rendering scheme, which improved the appearance of most of the elements of the Amiga user interface (windows, system gadgets, standard Boopsi classes, etc.). One element of the Amiga's GUI that escaped the NewLook was the menu system. For V39, Intuition added the NewLook to its menus. When Intuition renders NewLook menus, it gets the colors for the menu from the Palette Preferences set by the user. Before V39, Intuition used the window's DetailPen and BlockPen to draw the menu and the colors of the MenuItems depended on the MenuItem's IntuiText or Image structure. GadTools fully supports Intuition's NewLook menus. To make GadTools use the NewLook color scheme for a window's menus, an application needs to do two things. First, it needs to tell Intuition that it wants NewLook menu imagery for the window. It does this when opening the window by passing the {WA_NewLookMenus, TRUE} tag/value pair to OpenWindowTags(). Second, the application needs to remind GadTools that the window uses NewLook imagery for its menus. The application does this by passing the {GTMN_NewLookMenus, TRUE} tag/value pair to LayoutMenus(): struct VisualInfo *vi; LayoutMenus(menusready, vi, GTMN_NewLookMenus, TRUE, TAG_END); Instead of using the GTMN_NewLookMenus tag, it's possible to set the menu colors yourself by using the GTMN_FrontPen tag to set the pen number for rendering menu text. In addition to this tag, you must set the screen's BARDETAILPEN and BARTRIMPEN to match the menu text pen and set the BARBLOCKPEN to the color you want for the title bar. However, you cannot control how Intuition complements menu items and you do not automatically get the user's menu color preferences, so you will not get as perfect NewLook menu as you would by leaving it to the system. Gadgets Most GadTools gadgets received new attributes in V39. These include new IDCMP events, the ability to specify rendering pens, and scalable imagery. IDCMP Events Button, integer and string gadgets can send IDCMP_GADGETDOWN events by setting the GA_Immediate tag to TRUE. Disabling MX and listview gadgets join the other GadTools gadgets in having a disable attribute. Set the GA_Disabled tag to TRUE to disable, and FALSE to re-enable. Scalable Imagery Checkbox and MX gadgets are no longer fixed in size. You can scale them to any width and height. If you do not specify scaling, GadTools uses its built-in default dimensions. These dimensions, which are defined in , are CHECKBOXWIDTH and CHECKBOXHEIGHT for checkbox gadgets, and MXWIDTH by MXHEIGHT for MX gadgets. To scale a checkbox gadget, set the GTCB_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure. The default value of GTCB_Scaled is FALSE, meaning use the default size of 26 by 11, the values of CHECKBOXWIDTH and CHECKBOXHEIGHT, respectively. To scale an MX gadget, set the GTMX_Scaled tag to TRUE, and set the desired width and height in the ng_Width and ng_Height fields of the NewGadget structure. The default value of GTMX_Scaled is FALSE, meaning use the default size of 17 by 9, the values of MXWIDTH by MXHEIGHT, respectively. If you scale MX gadgets, you must also set the GTMX_Spacing tag to NewGadget.ng_TextAttr->ta_YSize + 1 to properly space the buttons with respect to the font. Rendering Pens, Display Format, Justification, Clipping and Display Size Application writers use number, text, and to some degree, slider gadgets, to present information to the user. The new attributes for these gadgets improve the presentation of the information. You can specify any pen for rendering the foreground and the background of number and text gadgets. This allows you to use color for emphasis or aesthetics. For example, you might use red as the foreground color in a text gadget for emphasis. You can also use C-language-like formatting strings for the displays, e.g., %lx would give you hexadecimal output in a number gadget. The Exec RawDoFmt() function processes this string, so refer to that function for details. Text clipping is another new attribute. It clips the display to fit within the borders of the gadget. This prevents the text or number from running over the border of a gadget if it's too large for the gadget. Along with text clipping, the number, text and slider gadgets can left, center and right justify their displays. Finally, you can specify the size of the string buffer that number and slider gadgets use when formatting their text. This buffer must be large enough to hold the entire string generated by the gadget, as the gadget doesn't do any bounds checking on the buffer. Underestimating the size of the buffer will cause the gadget to overwrite the buffer, overwriting whatever happens to follow the buffer in memory. For number gadgets, the GTNM_FrontPen tag specifies the pen to use for rendering the number. The default is DrawInfo->dri_Pens[TEXTPEN]). GTNM_BackPen specifies the pen to use for rendering the background of the number. The default is to use the background color of the gadget's window. GTNM_Justification specifies the type of justification within the gadget box. GTJ_LEFT renders the number flush with the left side of the gadget, GTJ_RIGHT renders the number flush with the right side, and GTJ_CENTER centers the number. The default is GTJ_LEFT. GTNM_Format specifies the C-language-like formatting string used to display the number. You must use the ``l'' (long) modifier. The default is ``%ld''. The gadget passes the formatting string to the exec.library function RawDoFmt(), which generates the string that appears in the number gadget. See the Autodoc for RawDoFmt() for more information on the formatting string. If an application changes the default formatting string with the GTNM_Format tag, the string that the number gadget displays may become significantly longer. For example, if the application uses the format string ``my number is %ld'', when the gadget processes the formatting string with RawDoFmt(), RawDoFmt() generates a string at least 14 characters long. By default, the gadget sets aside a 10 byte buffer for RawDoFmt() to use, so the formatting string above is too long for the default buffer. The tag GTNM_MaxNumberLen sets the size of this buffer. GTNM_Clipped controls text clipping. The default behavior differs between number gadgets with borders and number gadgets without borders. For bordered number gadgets, the default is TRUE--clip the display to fit within the gadget borders. For gadgets without borders, the default is FALSE--no clipping. Text gadgets also have a new set of attributes that correspond to the new number gadget attributes. These corresponding tags are: GTTX_FrontPen, GTTX_BackPen, GTTX_Justification, and GTTX_Clipped. There is no corresponding text gadget tag for GTMN_MaxNumberLen or GTMN_Format. Slider gadgets use the GTSL_Justification tag with the constants listed above (GTJ_LEFT, GTJ_RIGHT, and GTJ_CENTER) to control justification of the gadgets numeric display. The GTSL_MaxPixelLen tag specifies the maximum pixel size of the level display for any value of the slider. This is primarily useful when dealing with proportional fonts. The default is the font's character width (from the font's TextFont->tf_XSize field) multiplied by the value in the GTSL_MaxLevelLen tag. New Gadget-Specific Attributes MX gadgets can now have titles. The gadget obtains its title from the ng_GadgetText field of the NewGadget structure. The GTMX_TitlePlace tag specifies where to place the title. The possible values are: PLACETEXT_LEFT Right-align text on left side PLACETEXT_RIGHT Left-align text on right side PLACETEXT_ABOVE Center text above PLACETEXT_BELOW Center text below For compatibility reasons, GadTools will not put a title on the MX gadget if the GTMX_TitlePlace tag is not present. Listviews Listview gadget improvements include forced display of an item, highlighting of the selected item in the listview and custom callback hooks. The GTLV_MakeVisible tag specifies the number of the item that should be forced into the viewing area. It overrides the GTLV_Top tag. In V37, a listview identified its currently selected item by displaying it in a text gadget beneath the listview. The tag GTLV_ShowSelected specifies how the listview indicates which item is the currently selected item. If set to NULL, the listview places a highlight bar over the currently selected item. If GTLV_ShowSelected points to a string gadget, the listview displays the selected item in the string gadget in addition to a highlight bar. You can use callback hooks to render a listview's items. The listview in the V39 Palette Preferences editor uses a callback hook to display the standard user interface pens. The callback hook makes it possible for each item to display the pen color in addition to the pen name. The pen color appears in a little box at the left edge of each item in the listview. Palette GTPA_NumColors sets the number of colors to display in the palette gadget. This overrides the GTPA_Depth tag and allows numbers that are not powers of 2 (which was a limitation of the V37 palette gadget). The default is 2. Palette gadgets can now have their own array of pen numbers. GTPA_ColorTable is a pointer to a array of pen numbers. The array must contain at least as many entries as there are colors displayed in the palette gadget. The default is NULL which causes a 1-to-1 mapping of pen numbers. That means if you don't specify this tag, your palette will use pen number 0 through pen n-1, where n is the number of colors you set in GTPA_NumColors. For example, if you set GTPA_NumColors to 6 and don't specify GTPA_ColorTable, you will get a pen array of pens 0, 1, 2, 3, 4, and 5. A pen array you specify looks like this: UBYTE colors[8]= {1,2,15,6,0,3,8}; Setting GTPA_ColorTable to this array indicates that the palette pens are 1, 2, 15, 6, 0, 3 and 8, respectively. Note that you have to allocate pens to be certain you can use them and control them. See the Amiga OS V39 Developer Release Notes for information on allocating and sharing pens. You cannot use the GTPA_ColorTable tag with the GTPA_ColorOffset tag. The GTPA_ColorOffset tag specifies which pen to use as the first pen of a palette. For example, if you set it to 4, the first pen used in the palette will be pen 4. If you use the GTPA_ColorTable tag, the GTPA_ColorOffset tag is ignored. However, you can do color offsets with a color table by setting the value of the GTPA_ColorTable tag to point to the color table plus the offset you want. In the table above, you could specify pen 6 (the fourth member of the table) as the first pen to use by setting GPTA_ColorTable in this manner: CreateGadget(PALETTE_KIND, gad, &ng, GTPA_ColorTable, &colors[3], TAG_END); Note that the GTPA_NumColors tag is not present in the call above. This will default the number of colors to two, so the palette gadget created above will be a two color gadget that uses pens 6 and 0, the fourth and fifth pens in the array. Obtaining Gadget Attributes Prior to V39, the only way to obtain the attributes of a GadTools gadget was through the Code field of an IDCMP_GADGETUP IntuiMessage. In addition to having to wait until the user clicked on a gadget, this method limited you to obtaining one attribute at a time. A new GadTools function, GT_GetGadgetAttrs() obtains a gadget's attributes. You may call the function at any time after creating a gadget and for as many attributes as the function supports for that gadget. GT_GetGadgetAttrs() accepts a taglist of the attributes to obtain. An application passes it the address of the gadget, the address of the window containing the gadget, a NULL field (this field is reserved for later use and must be NULL for now), and a taglist. Each attribute value pair in the taglist supplies the ID of the tag to get (in ti_Tag) and an address where GT_GetGadgetAttrs() can store the tag's value. Since all tag values are longwords, expect GT_GetGadgetAttrs() to copy a longword for each attribute you request. The function returns the number of attributes it obtained. LONG how_many, top_item = 0, selected_item = 0; how_many = GT_GetGadgetAttrs( listview_gad, win, NULL, GTLV_Top, &top_item, GTLV_Selected, &selected_item, TAG_DONE ); How_many contains the number of gadget attributes GT_GetGadgetAttrs() obtained. GT_GetGadgetAttrs() copies the value of the listview top and the selected item into top_item and selected_item, respectively. Use longword targets to hold the returned values. GT_GetGadgetAttrs() supports GA_Disabled (TRUE if the gadget is disabled; FALSE if the gadget is active) for all GadTools gadgets except text and number gadgets. Other attributes are specific to each gadget as follows: Checkbox - GTCB_Checked returns TRUE if the checkbox gadget is checked, or FALSE if the gadget is not checked. Cycle - GTCY_Active returns the ordinal number, counting up from zero, of the active choice. GTCY_Labels returns a pointer to the NULL-terminated array of choices. Integer - GTIN_Number returns the contents of the gadget. Listview - GTLV_Top returns the ordinal number, counting up from zero, of the top item. GTLV_Selected returns the ordinal number of the selected item. GTLV_Labels returns a pointer to the List structure associated with the gadget. MX - GTMX_Active returns the ordinal number, counting up from zero, of the active selection. Palette - GTPA_Color returns the ordinal number of the selected color. This number corresponds to the selected color's position in the palette's GTPA_ColorTable array. GTPA_ColorOffset returns the ordinal number of the first color used in the palette. GTPA_ColorTable returns a pointer to the table of pen numbers used for the gadget, if there is one. Scroller - GTSC_Top returns the number of the top line visible in the scroller. GTSC_Total returns the total number of lines in the scroller. GTSC_Visible returns the number of visible lines in the scroller. Slider - GTSL_Min returns the minimum value of the slider. GTSL_Max returns the maximum value of the slider. GTSL_Level returns the current level of the slider. String - GTST_String returns a pointer to the gadget's buffer. Text - GTTX_Text returns a pointer to the gadget's buffer. Message Handling - ExtIntuiMessage Structure For V39, the IntuiMessage structure has been extended to allow for tablet support. The GadTools message handling functions--GT_FilterIMsg(), GT_GetIMsg(), GT_PostFilterIMsg() and GT_ReplyIMsg()--work with the extended IntuiMessage structure, ExtIntuiMessage, but are backwards compatible with IntuiMessage. Gadget Help All GadTools gadgets support Intuition's gadget help feature. You enable this by calling the intuition.library function HelpControl(). Gadget help is either on or off for all GadTools gadgets in a window; you cannot selectively enable it for certain gadgets as you can with Intuition gadgets. For more information, refer to page IV-114 of the ``Boopsi in Release 3'' article in the January/February 1993 issue of Amiga Mail. Bevel Box Bevel boxes now come in three types that you specify with GTBB_FrameType. BBFT_BUTTON generates the type of box used around button gadgets. BBFT_RIDGE generates the type of box used for string gadgets. BBFT_ICONDROPBOX generates a box suitable for a standard icon drop box imagery. The default is BBFT_BUTTON. These frame types are similar to the Boopsi imageclass frame types FRAME_BUTTON, FRAME_RIDGE, and FRAME_ICONDROPBOX, that are pictured on page IV-120 of the ``Boopsi in Release 3'' article in the January/February 1993 issue of Amiga Mail. Example Code - NewGadgets.c The example code below is a demonstration of some of the V39 GadTools changes and how to specify them in your code. You'll notice that it lacks many of the features required to actually use the gadgets. This is by design. The intent is for you to modify an existing application using the example as a guide. @{" NewGadgets.c " link "IV-125/NewGadgets.c/MAIN"} NewGadgets.c produced the screen shot below. @{" Figure 1 - Some New GadTools Features " link "IV-125/Figure1.ilbm/MAIN"} @ENDNODE