BCI NET 2

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET 2 / BCI NET 2.iso / archives / programming / e / gtlayout4e.lha / gtlayout.doc next >

Wrap

Text File | 1995-03-07 | 94.4 KB | 2,731 lines

TABLE OF CONTENTS gtlayout.library/--version-- gtlayout.library/--background-- gtlayout.library/LT_Activate gtlayout.library/LT_BeginRefresh gtlayout.library/LT_BuildA gtlayout.library/LT_CreateHandleTagList gtlayout.library/LT_DeleteHandle gtlayout.library/LT_DeleteWindowLock gtlayout.library/LT_EndGroup gtlayout.library/LT_EndRefresh gtlayout.library/LT_Exit gtlayout.library/LT_Fixed2String gtlayout.library/LT_FixedMult gtlayout.library/LT_GetAttributesA gtlayout.library/LT_GetCode gtlayout.library/LT_GetIMsg gtlayout.library/LT_HandleInput gtlayout.library/LT_Init gtlayout.library/LT_LabelChars gtlayout.library/LT_LabelWidth gtlayout.library/LT_LayoutMenusA gtlayout.library/LT_LevelWidth gtlayout.library/LT_LockWindow gtlayout.library/LT_NewA gtlayout.library/LT_PressButton gtlayout.library/LT_RebuildTagList gtlayout.library/LT_ReplyIMsg gtlayout.library/LT_SetAttributesA gtlayout.library/LT_ShowWindow gtlayout.library/LT_String2Fixed gtlayout.library/LT_UnlockWindow gtlayout.library/LT_UpdateStrings gtlayout.library/--version-- gtlayout.library/--version-- This document describes gtlayout.library v5.12 or higher. Do not assume that previous library releases support the same features. gtlayout.library/--background-- gtlayout.library/--background-- 1. General information 1.1 Purpose The GUI code included in this archive helps to create user interfaces using gadtools.library with a minimum of effort. The code automatically takes care of the font to be used, making the user interface font independent. Localizing support is built right into the code, just install a callback hook and pass numeric IDs for the gadget labels: the code will invoke your hook in order to get the text required. Keystroke activation of gadgets is also taken care of, in fact the code will -- unless told not to do so -- assign keyboard shortcuts to the gadgets created all on its own. Every effort has been made to make the code reentrant, so it can be put into a shared library. If a user interface does not fit onto a screen provisions are made to choose a smaller font and to rescale the window contents until they fit. Last but not least the user interface code offers transparent extensions to the standard gadtools.library objects, such as LISTVIEW_KIND objects which respond to double-clicks or STRING_KIND objects which can be used to enter password text as they will not display the characters entered. 1.2 Distribution The code is *free*, you don't need to pay any money to use it, nor do you need to quote my name in the documentation, the program or anywhere else. You are allowed to make changes to the code, but if you stumble across any bugs or even know how to fix them, please let me know. It does not matter whether you intend to sell a program to use the code, use the code in shareware, gift-ware, freeware or etc.-ware programs: the code still remains royalty-free. 1.3 Caveats The code is pretty large, about 40K-60K bytes in size. Not all gadtools.library type objects are supported, notably GENERIC_KIND objects. The code is not as flexible as gadtools.library, so certain things which are easily done using gadtools.library may be pretty difficult or even impossible. The code is written entirely in `C' and requires SAS/C to compile. Some parts of the code are highly recursive; I haven't measured how many stack they might require in certain cases, but I recommend that you don't use the grouping feature too much. The data structures required to create and maintain the user interface are huge, a single window might require more than 4K-6K of memory. Proportional font support only works well starting with Kickstart v39 and up, v2.04 will probably not look quite that pretty. 2. Programming 2.1 Client libraries required You need to have SysBase and GadToolsBase initialized in order to make use of the code, i.e. your code has to do WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes use of the memory pools introduced in exec.library v39, but calls the equivalent routines in amiga.lib. Note: as of this writing the pools code in amiga.lib v40.14 is broken, so you need to link with Mike Sinz' fixed pools.lib. 2.2 Invocation procedure The typical invocation procedure looks roughly like this: LT_Init(); : : LT_CreateHandleTags(); LT_New(); : : LT_New(); LT_Build(); LT_HandleInput(); LT_DeleteHandle(); : : LT_Exit(); You need to call LT_Init() only once in your program, it will initialize the libraries and global data structures required by the user interface code. When you are finished with the user interface and your program is about to exit you need to call LT_Exit() or memory will get lost. Note that LT_Init() is not protected against multiple invocations. If called repeatedly memory will get lost which can never be reclaimed. However, LT_Exit() is protected against multiple invocations, you can also call it before ever giving LT_Init() a call, but I doubt this would make much sense. If you are using the shared gtlayout.library no call to LT_Init()/LT_Exit() is necessary as these calls are already wrapped into the library opening code. Before you can actually start building a window layout a call to LT_CreateHandleTags() needs to be made. You need to pass in a pointer to the Screen your user interface window is to be opened on and, optionally, a few tags to control the look and performance of the interface. *Never* close the screen in question before calling LT_DeleteHandle() or nasty things will happen. For public screens the code will try to lock the screen in question. With the handle LT_CreateHandleTags() returned you can call LT_New() to build the user interface. When finished a call to LT_Build() will finally open a window and place the gadgets inside. A pointer to the Window created will be returned, ready to be used for the WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg() loop. When finished, a call to LT_DeleteHandle() will close the window and release all the memory associated with it. The design of the interface code is similar to the corresponding calls in gadtools.library, i.e. you don't need to worry about LT_New() failing to allocate memory for the objects required. When it comes to LT_Build() the code will know about any trouble which would show up during previous invocations of LT_New(). In essence, if LT_Build() returns NULL something is wrong. 2.3 Hierarchic grouping The basic building block of the user interface is a group, either a horizontal or a vertical group. Adding gadgets or other objects to a horizontal group will place them side by side from left to right. A vertical group causes objects to be place from top to bottom in one straight line. Groups help to arrange objects neatly stacked, centered and properly aligned with other members of the group. MUCHO IMPORTANTE: there is a bug lurking in the code which I never had the luck to find and fix. One would expect to create user interface structures like this: <group start> <button> <list> <group start> <slider> <text> <group end> <button> <group end> However, it is in fact not possible to mix gadgets and groups. Thus, the user interface structure would have to look like this: <group start> <group start> <button> <list> <group end> <group start> <slider> <text> <group end> <group start> <button> <group end> <group end> Or in other words: groups only mix with other groups. You build groups using three different object types. In this context `object type' refers to a specific numeric value the LT_New() routine knows which will cause it to add another leaf to the user interface structure tree. Here is an example: struct LayoutHandle *Handle; if(Handle = LT_CreateHandleTags(NULL, LH_AutoActivate,FALSE, TAG_DONE)) { struct Window *Window; LT_New(Handle, LA_Type, VERTICAL_KIND, /* A vertical group. */ LA_LabelText, "Main group", /* Group title text. */ TAG_DONE); { LT_New(Handle, LA_Type, BUTTON_KIND, /* A plain button. */ LA_LabelText, "A button", LA_ID, 11, TAG_DONE); LT_New(Handle, LA_Type, XBAR_KIND, /* A separator bar. */ TAG_DONE); LT_New(Handle, LA_Type, BUTTON_KIND, /* A plain button. */ LA_LabelText, "Another button", LA_ID, 22, TAG_DONE); LT_New(Handle, LA_Type, END_KIND, /* This ends the current group. */ TAG_DONE); } if(Window = LT_Build(Handle, LAWN_Title, "Window title", LAWN_IDCMP, IDCMP_CLOSEWINDOW, WA_CloseGadget, TRUE, TAG_DONE)) { struct IntuiMessage *Message; ULONG MsgQualifier, MsgClass; UWORD MsgCode; struct Gadget *MsgGadget; BOOL Done = FALSE; do { WaitPort(Window -> UserPort); while(Message = GT_GetIMsg(Window -> UserPort)) { MsgClass = Message -> Class; MsgCode = Message -> Code; MsgQualifier = Message -> Qualifier; MsgGadget = Message -> IAddress; GT_ReplyIMsg(Message); LT_HandleInput(Handle,MsgQualifier,&MsgClass,&MsgCode,&MsgGadget); switch(MsgClass) { case IDCMP_CLOSEWINDOW: Done = TRUE; break; case IDCMP_GADGETUP: switch(MsgGadget -> GadgetID) { case 11: printf("First gadget\n"); break; case 22: printf("Second gadget\n"); break; } break; } } } while(!Done); } LT_DeleteHandle(Handle); } The example creates one single group, places a few objects inside, calls the layout routine, handles the input and finally cleans things up again. This example also shows that you *need* at least one group in your tree (to form the root) in order to get things to work. The input loop requires you to call LT_HandleInput() in order to get the user interface code to filter out certain events and to update internal information. The data passed in must have been processed via the gadtools.library routines. You *must not* call LT_HandleInput() before GT_ReplyIMsg() is called since the routine may call intuition.library and gadtools.library routines which in turn might lead to a system lock-up if the message has not been processed yet. The first thing to do after LT_HandleInput() has done whatever was necessary to the data you passed in is examine the MsgClass variable. The user interface code will `fake' certain message events using the variables passed in, *do not* use any other data gathered from the original IntuiMessage. The MsgClass may include event types you did not ask for, i.e. the IDCMP flags of the window opened will be set according to the objects you added to the window. Also, the IDCMP_IDCMPUPDATE message class will show up for certain objects. More on this later in this document. 2.4 Setting and getting object attributes The mechanism to update and query object attributes does not exactly match the familiar gadtools.library interface. In fact, the routine to change gadget attributes will forward the tagitem list passed in to gadtools.library/GT_SetGadgetAttrs(). On the other hand the routine to query object attributes does not work like gadtools.library/GT_GetGadgetAttrs(). The user interface code assumes that all objects it can handle and create posess certain attributes unique to the type of the object in question. For example, the unique attribute of a STRING_KIND object would be a pointer to the string it `contains'. The unique attribute of a SLIDER_KIND object is the current slider position. The LT_GetAttributes() routine will return this attribute, but also accept a tagitem list to fill in for certain special tag values. 2.5 Extra data Once a LayoutHandle has been created the interface code will provide you with a number of information concerning the screen the handle has been attached to. This information includes the DrawInfo structure of the screen, the VisualInfo data and the Screen address. This information is read-only. 2.6 Menus With a LayoutHandle available a routine calld LT_LayoutMenuTags() will create a standard Intuition menu structure via gadtools.library which can be passed to LT_Build(). Note that this routine does not modify any data passed in, it does neither attach the menu created to the LayoutHandle passed in, nor does it change the NewMenu table. 2.7 Localization All object and menu creation routines support localization via a Hook callback interface, i.e. you can pass a pointer to an initialized Hook structure to LT_CreateHandleTags() which will later be used to supply label and list text for objects created. The Hook callback routine is called in the following fashion: String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,LONG ID) D0 A0 A2 A1 Or in other words: a locale string ID is passed in, the routine is supposed to look up the string to match this ID and to return it. 2.8 Object types to generate IDCMP_IDCMPUPDATE events Certain objects convey extra information which is merged into the `fake' input stream passed to the client calling LT_HandleInput(). These objects are: STRING_KIND TEXT_KIND The user pressed the `select' button which belongs to this gadget. The MsgGadget pointer indicates the STRING_KIND/TEXT_KIND object the `select' button belongs to. LISTVIEW_KIND The user double-clicked on an entry. The entry number is returned in the MsgCode variable. The MsgGadget pointer indicates the LISTVIEW_KIND object the user has clicked on. 2.9 Keystroke activation Unless forbidden via the the LA_NoKey tag item the user interface code will pick the keyboard shortcuts for all gadgets on its own. The currently active global console keymap will be checked at the time when LT_Init() is called in order to make sure subsequent calls to LT_Build() will use only keys the user can press on the keyboard. Double-dead keys are also excluded from the table created. This avoids problems with gadget labels such as "éééé" which would require the user to hit two keys in a row to activate the gadget. If the window created happens to feature a close gadget pressing the `Esc' key will cause the client to receive an IDCMP_CLOSEWINDOW event. A single LISTVIEW_KIND object may receive special treatment if the LALV_CursorKey tag is used: the user will be able to operate the listview using the cursor keys. Note: this will will also keep the user interface code from choosing a special keystroke from the gadget label. The user will be able to operate a single BUTTON_KIND object using the return key if the LABT_ReturnKey tag is used. A recessed frame will be drawn around the button hit box to indicate its special status. Pressing the Tab key can be bound to operate a cycle or mx kind object. 3. Credits The original design is based upon the user interface layout code used by `term' 3.1. I put the first version of the layout routines together back in Summer 1993 when I wanted to write the follow-up to `term' v3.4. Martin Taillefer rewrote large parts of the code, added new routines and generally improved the performance of the layout process. Kai Iske and Christoph Feck helped to iron out the remaining bugs and piled up bug reports and enhancement requests. gtlayout.library/LT_Activate gtlayout.library/LT_Activate NAME LT_Activate -- Activate a string type gadget. SYNOPSIS LT_Activate(Handle,ID); A0 D0 VOID LT_Activate(LayoutHandle *,LONG); FUNCTION The equivalent to intuition.library/ActivateGadget(). INPUTS Handle - Pointer to LayoutHandle structure. ID - ID of Gadget to activate. RESULT none SEE ALSO intuition.library/ActivateGadget gtlayout.library/LT_BeginRefresh gtlayout.library/LT_BeginRefresh NAME LT_BeginRefresh -- Optimized window refreshing SYNOPSIS LT_BeginRefresh(Handle) A0 VOID LT_BeginRefresh(LayoutHandle *); FUNCTION If you wish to handle window refreshing all on your own, you might want to use the LT_BeginRefresh...LT_EndRefresh pair in your program. By default the user interface layout engine will automatically intercept IDCMP_REFRESHWINDOW events and react to them accordingly. INPUTS Handle - Pointer to a LayoutHandle structure. RESULT none. SEE ALSO intuition.library/BeginRefresh intuition.library/EndRefresh gtlayout.library/LT_EndRefresh gtlayout.library/LT_BuildA gtlayout.library/LT_BuildA NAME LT_BuildA -- turn the user interface specs into a window and gadgets. SYNOPSIS Window = LT_BuildA(Handle,Tags); D0 A0 A1 struct Window *LT_BuildA(LayoutHandle *,struct TagItem *); Window = LT_Build(Handle,...); struct Window *LT_Build(LayoutHandle *,...); FUNCTION This is the big one. After building up a user interface specification using LT_NewA() a call to LT_BuildA() will finally lay out the single user interface elements, open a window and put the gadgets, etc. inside. The code tries to fit all the gadgets into the window, but if it runs out of space it will fall back to a different font and rescale the user interface objects to match it. It will first fall back onto the system default font. If unsuccessful it will as a last resort try to use topaz.font/8. INPUTS Handle - Pointer to a LayoutHandle structure. Tags - Pointer to TagItem list controlling window and layout attributes. TAGS All the tag values given are passed straight away to OpenWindowTags(), see intuition.doc for more information. In addition to this a number of private tag values are supported: LAWN_Menu (struct Menu *) - The menu to attach to the window, the IDCMP flags will be updated to include IDCMP_MENUPICK if this tag is used. LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the window user port. The MsgPort will be attached using the common ModifyIDCMP() method, closing the window will first remove and reply all pending messages at this port. LAWN_Left (LONG) - The left edge position the window is to use. This effectively overrides any horizontal alignment flags. NOTE: the code may choose to ignore this value if it finds that the window will not fit onto the screen unless the left edge position is changed. LAWN_Top (LONG) - The top edge position the window is to use. This effectively overrides any vertical alignment flags. NOTE: the code may choose to ignore this value if it finds that the window will not fit onto the screen unless the top edge position is changed. LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking on this gadget will cause the window to shrink/zoom back to its original position. This differs from the WA_Zoom tag behaviour. When the window zooms back to its original position the gadgets are automatically refreshed. Default: FALSE LAWN_MaxPen (LONG) - The maximum rendering pen index your code will use. Since you are -- with some restrictions -- allowed to render into the window created you may want to avoid silly side effects if drawing images or other colourful textures which do not share the common user interface colours. By default the layout code will change the maximum rendering pen number for the window to include only the user interface pen colours. This can, but need not disturb your own private window rendering. Look up graphics.library/SetMaxPen for more information. Default: determined by looking up Screen->DrawInfo.dri_Pens LAWN_BelowMouse (BOOL) - This instructs the layout routine to centre the window created -- if possible -- below the mouse pointer. This effectively ignores any left edge, top edge or alignment settings. Default: FALSE LAWN_MoveToWindow (BOOL) - When the window is finally open the user interface code will try to make sure the entire window is visible on the screen, this may involve moving the currently visible portion of an autoscrolling screen. Default: TRUE LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events automatically. Default: TRUE LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user presses the "Help" key. See gtlayout.h for more information. Default: NULL LAWN_Parent (struct Window *) - Parent window to centre the child window in. Default: NULL LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow() until the child window is closed. NOTE: requires LAWN_Parent attribute. Default: FALSE LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created. When in zoomed state, the window will be as small as possible, showing only the window title and window gadgets: NOTE: this tag implies LAWN_Zoom,TRUE Default: FALSE LAWN_Title (STRPTR) - The window title to use. Use this tag in place of WA_Title or you will break the layout code. Default: no title LAWN_Bounds (struct IBox *) - Bounds to centre the window in. Default: NULL LAWN_ExtraWidth (LONG) - Extra width to add into the calculation when opening the window. Default: 0 LAWN_ExtraHeight (LONG) - Extra height to add into the calculation when opening the window. Default: 0 LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you will break the object handling code. LAWN_AlignWindow (UWORD) - Alignment information for the window, must be a mask made from the following bit values: ALIGNF_RIGHT - Align to screen right edge ALIGNF_LEFT - Align to screen left edge ALIGNF_TOP - Align to screen top edge ALIGNF_BOTTOM - Align to screen bottom edge Unless forbidden (such as by passing ALIGNF_RIGHT|ALIGNF_TOP) the window will be centered horizontally and/or vertically. RESULT Window - Pointer to a Window structure. SEE ALSO intuition.library/OpenWindow intuition.library/OpenWindowTagList gtlayout.library/LT_CreateHandleTagList gtlayout.library/LT_CreateHandleTaglist NAME LT_CreateHandleTagList -- Allocate auxilary data required by LT_New() and LT_BuildA(). SYNOPSIS Handle = LT_CreateHandleTagList(Screen,Tags); D0 A0 A1 LayoutHandle *LT_CreateHandleTagList(struct Screen *,struct TagItem *); Handle = LT_CreateHandleTags(Screen,...); struct LayoutHandle *LT_CreateHandleTags(struct Screen *,...); FUNCTION Memory is allocated, tables are set up and data is collected on a screen a user interface is to be opened on. This involves calculating the screen font parameters. INPUTS Screen - Pointer to the screen the user interface is to use. Passing NULL will cause the default public screen to be used. NOTE: if NULL is passed the default public screen will stay locked until LT_DeleteHandle() is called. Tags - Tag values to control certain aspects of the user interface created. TAGS LH_AutoActivate (BOOL) - Set to TRUE if you want the interface to always keep a string gadget active if possible. Hitting the return key will then cause the next following string gadget to get activated, either cycling through all the string gadgets available or stopping at the next string gadget to have the LAST_LastGadget attribute set. Default: TRUE LH_UserData (APTR) - Store user specific data in the LayoutHandle->UserData entry. NOTE: This tag requires gtlayout.library v9 and the corresponding entry in the LayoutHandle exists only under gtlayout.library v9 and up. *NEVER* write to this entry, use LT_SetAttributes() instead. LH_LocaleHook (struct Hook *) - The hook to call when locale string IDs are to be mapped to strings. The hook function is called with the following parameters: String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle, D0 A0 A2 LONG ID) A1 The function is to look up the string associated with the ID passed in and return the string. Default: no locale hook LH_Font (struct TTextAttr *) - The text font to use when creating the gadgets and objects. Default: Screen->Font LH_CloningPermitted (BOOL) - If a window will not fit onto the screen the user interface is intended for, the layout engine will scale the interface data down while stepping down in font size. If all this fails, the engine will open a custom screen for the window; this process is called "cloning". The LH_CloningPermitted tag controls whether the engine will actually try to open the custom screen or just return NULL when LT_Build fails. Default: TRUE LH_EditHook (struct Hook *) - You can specify a default string gadget editing hook to be used for all following string gadgets. Your hook should obey the same rules that apply to hooks passed via GTST_EditHook/GTIN_EditHook. Default: NULL LH_ExactClone (BOOL) - This tag works in conjunction with the LH_CloningPermitted tag. By default the layout engine will try to replicate only the basic characteristics of the screen the window was intended to open on. This may result in a screen which uses less colours than the original screen. You can force the engine to make an almost exact clone of the original screen by passing the LH_ExactClone tag with a value of TRUE. Default: FALSE LH_MenuGlyphs (BOOL) - This tag will make the layout engine fill in the AmigaGlyph and CheckGlyph entries of the LayoutHandle if running under Kickstart 3.0 or higher. The corresponding images will be scaled to fit the actual screen aspect ratio values and can later be used for menu layout. Default: FALSE LH_Parent (struct Window *) - You can pass a pointer to the parent window of the window you intend to open using the user interface layout engine. The new window will open inside the boundaries of the parent window. If the size does not fit, it will be opened centered over the parent window. Default: NULL LH_BlockParent (BOOL) - This tag works in conjunction with the LH_Parent tag. If in effect, will block the parent window via LT_LockWindow until the new window is closed, after which the parent window is unlocked again. Default: FALSE LH_SimpleClone (BOOL) - This tag works in conjunction with the LH_CloningPermitted tag. It will make the layout engine forget most information about the original screen the user interface was intended for. In short, it will open a simple default screen for the interface. Default: FALSE LH_ExitFlush (BOOL) - When the LayoutHandle is finally disposed of with LT_DeleteHandle() all variables maintained by the input handling code will be flushed. For example, if you would use the LA_STRPTR tag for STRING_KIND objects the last string gadget contents would be copied into the buffer pointed to by LA_STRPTR. If you do not want to use this feature, disable it with "LH_ExitFlush,FALSE". Default: TRUE (requires gtlayout.library v9 or higher) RESULT Handle - Pointer to a LayoutHandle structure. gtlayout.library/LT_DeleteHandle gtlayout.library/LT_DeleteHandle NAME LT_DeleteHandle -- Release storage space allocated by LT_CreateHandleTagList, closing windows, removing gadgets, etc. SYNOPSIS LT_DeleteHandle(Handle); A0 VOID LT_DeleteHandle(LayoutHandle *); FUNCTION Windows and gadgets created by LT_CreateHandleTagList() are removed, any associated memory is deallocated. INPUTS Handle - Pointer to a LayoutHandle structure created by LT_CreateHandleTaglist(). Passing NULL is harmless. RESULT none SEE ALSO gtlayout.library/CreateHandleTagList gtlayout.library/LT_DeleteWindowLock gtlayout.library/LT_DeleteWindowLock NAME LT_DeleteWindowLock -- Remove all locks from a window SYNOPSIS LT_DeleteWindowLock(Window); A0 VOID LT_DeleteWindowLock(struct Window *); FUNCTION Before closing a locked window you should call this routine which will remove all outstanding locks from it. INPUTS Window - Pointer to window structure. RESULT none gtlayout.library/LT_EndGroup gtlayout.library/LT_EndGroup NAME LT_EndGroup -- end a group declaration. SYNOPSIS LT_EndGroup(Handle); A0 VOID LT_EndGroup(LayoutHandle *); FUNCTION This is just a short form of LT_New(Handle, LA_Type, END_KIND, TAG_DONE); It helps to save (some) space. INPUTS Handle - Pointer to LayoutHandle. RESULT none gtlayout.library/LT_EndRefresh gtlayout.library/LT_EndRefresh NAME LT_EndRefresh -- Optimized window refreshing SYNOPSIS LT_EndRefresh(Handle) A0 VOID LT_EndRefresh(LayoutHandle *); FUNCTION If you wish to handle window refreshing all on your own, you might want to use the LT_BeginRefresh...LT_EndRefresh pair in your program. By default the user interface layout engine will automatically intercept IDCMP_REFRESHWINDOW events and react to them accordingly. INPUTS Handle - Pointer to a LayoutHandle structure. RESULT none. SEE ALSO intuition.library/BeginRefresh intuition.library/EndRefresh gtlayout.library/LT_BeginRefresh gtlayout.library/LT_Exit gtlayout.library/LT_Exit NAME LT_Exit -- Clean up user interface allocations SYNOPSIS LT_Exit(); VOID LT_Exit(VOID); FUNCTION When you are finished with user interface creation and do not not need the code any more you should call this routine. It will free all the memory allocated by LT_Init(), close libraries, etc. INPUTS none RESULT none NOTES This routine is available in the link library only. gtlayout.library/LT_Fixed2String gtlayout.library/LT_Fixed2String NAME LT_Fixed2String -- Convert a fixed-point number into an alphanumeric string. SYNOPSIS LT_Fixed2String(Fixed,String); D0 D1 VOID LT_Fixed2String(FIXED,STRPTR); FUNCTION This routine implements a service similar to ftoa(). It converts a fixed point number into an ASCII representation. INPUTS Fixed - Fixed point numeric value String - Buffer to receive the converted value. This buffer must be at least 12 bytes large. NOTES The decimal point will be taken from the current locale. If locale.library is not installed in your system, the `.' character will be used instead. The arguments are passed in D0 and D1, this is *not* a typo. SEE ALSO gtlayout.library/LT_String2Fixed gtlayout.library/LT_FixedMult gtlayout.library/LT_FixedMult NAME LT_FixedMult -- Multiply a fixed-point number with an integer value. SYNOPSIS Fixed = LT_FixedMult(Fixed,Factor) D0 D0 D1 FIXED LT_FixedMult(FIXED,ULONG); FUNCTION The layout engine provides only a fixed point multiplication routine. You need to implement other numeric operations on your own. INPUTS Fixed - Fixed-point number to be multiplied. Factor - Integer value to multiply fixed-point number with. RESULT Fixed - Product gtlayout.library/LT_GetAttributesA gtlayout.library/LT_GetAttributesA NAME LT_GetAttributesA -- Inquire information on a gadget. SYNOPSIS Value = LT_GetAttributesA(Handle,ID,Tags); D0 A0 D0 A1 LONG LT_GetAttributesA(LayoutHandle *,LONG ID,struct TagItem *); Value = LT_GetAttributes(Handle,ID,...); LONG LT_GetAttributes(LayoutHandle *,LONG ID,...); FUNCTION All objects created by the user interface layout code posess certain unique properties. The LT_GetAttributes() function will will inquire this information and return it. The implementation differs from gadtools.library/GT_GetGadgetAttrs in that you can inquire only a small subset of the object properties possible via the taglist passed in. INPUTS Handle - Pointer to LayoutHandle structure. ID - ID number of the object to inquire information about. This is the same value you passed via LA_ID to LT_New() when you created this object. Tags - TagItem list to receive information about the object in question. TAGS LA_Left (LONG *) - Left edge of object. LA_Top (LONG *) - Top edge of object. LA_Width (LONG *) - Width of object. LA_Height (LONG *) - Height of object. LA_Chars (LONG *) - Width of object measured in character widths. (requires gtlayout.library v9 or higher) LA_Lines (LONG *) - Height of object measured in character heights. (requires gtlayout.library v9 or higher) LA_LabelLeft (LONG *) - Left edge of label text. (requires gtlayout.library v9 or higher) LA_LabelTop (LONG *) - Top edge of label text. (requires gtlayout.library v9 or higher) RESULT The result depends on the object type: VERTICAL_KIND: HORIZONTAL_KIND: active page FRACTION_KIND: current LAFC_Number value SCROLLER_KIND: current GTSC_Top value TAPEDECK_KIND: current LATD_Pressed value LEVEL_KIND: current LAVL_Level state CHECKBOX_KIND: current GTCB_Checked state LISTVIEW_KIND: current GTLV_Selected state MX_KIND: current GTMX_Active state CYCLE_KIND: current GTCY_Active state PALETTE_KIND: current GTPA_Color state SLIDER_KIND: current GTSL_Level state GAUGE_KIND: current LAGA_Percent state STRING_KIND: pointer to current string PASSWORD_KIND: pointer to current string INTEGER_KIND: number currently entered gtlayout.library/LT_GetCode gtlayout.library/LT_GetCode NAME LT_GetCode -- Easy raw key event to ANSI conversion. SYNOPSIS Key = LT_GetCode(Qualifier,Class,Code,Gadget); D0 D0 D1 D2 A0 WORD LT_GetCode(ULONG,ULONG,UWORD,struct Gadget *); FUNCTION The user interface layout engine can convert IDCMP_RAWKEY events into ANSI codes. Pass in the data you copied from the IntuiMessage here. INPUTS Qualifier - Copied from IntuiMessage->Qualifier Class - Copied from IntuiMessage->Class Code - Copied from IntuiMessage->Code Gadget - Copied from IntuiMessage->IAddress RESULT Key - ANSI code generated from the input data or -1 if no such code was to be generated. gtlayout.library/LT_GetIMsg gtlayout.library/LT_GetIMsg NAME LT_GetIMsg -- Retrieve the next pending IntuiMessage from the window associated with a LayoutHandle. SYNOPSIS IntuiMessage = LT_GetIMsg(Handle); D0 A0 struct IntuiMessage *LT_GetIMsg(LayoutHandle *); FUNCTION This routine will handle most of the input loop for you. Just pass the pointer to the layout handle in, check if the result code is non-null, copy the data you need and reply the message via LT_ReplyIMsg(). You will still need to wait for new input, as LT_GetIMsg will poll the MsgPort of the window. INPUTS Handle - Pointer to LayoutHandle structure RESULT IntuiMessage - Pointer to IntuiMessage structure NOTES You *must not* make any assumptions about the contents of the IntuiMessage structure except for the following entries: Class Code Qualifier IAddress When finished, you must dispose the IntuiMessage via LT_ReplyIMsg or memory will be lost which can never be reclaimed. DO NOT CALL LT_HandleInput() ON THE DATA YOU RECEIVE FROM LT_GetIMsg() AS LT_GetIMsg() ALREADY DOES ALL THE MAGIC LT_HandleInput() OTHERWISE WOULD NEED TO DO! IF YOU STILL DO CALL LT_HandleInput() ON THE DATA YOU WILL RECEIVE `GHOST' EVENTS. SEE ALSO gtlayout.library/LT_ReplyIMsg gtlayout.library/LT_HandleInput gtlayout.library/LT_HandleInput NAME LT_HandleInput -- Filter IntuiMessage data. SYNOPSIS LT_HandleInput(Handle,Qualifier,Class,Code,Gadget); A0 A1 A2 A2 A3 VOID LT_HandleInput(LayoutHandle *,ULONG,ULONG *, UWORD *,struct Gadget **); FUNCTION In order to keep track of user interface actions, such as keys getting pressed, sliders getting moved, etc. your code is to call LT_HandleInput() with data copied from the IntuiMessage it has just received and replied. NOTE: do not call this routine before you have actually replied the IntuiMessage received or weird things may happen. INPUTS Handle - Pointer to a LayoutHandle structure. Qualifier - The Qualifier value copied from the IntuiMessage structure. Class - Pointer to the ULONG variable which holds the value copied from the Class entry of the IntuiMessage structure. Code - Pointer to the UWORD variable which holds the value copied from the Code entry of the IntuiMessage structure. Gadget - Pointer to the Gadget value copied from the IAddress entry of the IntuiMessage structure. EXAMPLE struct IntuiMessage *IntuiMessage; ULONG Qualifier,Class; UWORD Code; struct Gadget *Gadget; for(;;) { WaitPort(Window -> UserPort); while(IntuiMessage = GT_GetIMsg(Window -> UserPort)) { Class = IntuiMessage -> Class; Code = IntuiMessage -> Code; Qualifier = IntuiMessage -> Qualifier; Gadget = IntuiMessage -> Gadget; GT_ReplyIMsg(IntuiMessage); LT_HandleInput(Handle,Qualifier,&Class,&Code,&Gadget); } } RESULT none gtlayout.library/LT_Init gtlayout.library/LT_Init NAME LT_Init -- Initialize user interface code. SYNOPSIS LT_Init(); VOID LT_Init(VOID); FUNCTION You need to initialize the user interface code only once, so it can set up its internals, open libraries, etc. The code has to be initialized before any user interface creation can take place. INPUTS none RESULT none NOTES This routine is available in the link library only. gtlayout.library/LT_LabelChars gtlayout.library/LT_LabelChars NAME LT_LabelChars -- Calculate the width of a a string according to the user interface font associated with a LayoutHandle. SYNOPSIS Length = LT_LabelChars(Handle,Label); D0 A0 A1 LONG LT_LabelChars(struct LayoutHandle *,STRPTR); FUNCTION Calculates the width of a string according to the user interface font used. The width is then converted to a number of characters suitable for using with the LA_Chars tag item when calling LT_New(). INPUTS Handle - Pointer to LayoutHandle structure. Label - Pointer to string. RESULT Length - Number of characters that are considered equivalent to the string length in pixels. gtlayout.library/LT_LabelWidth gtlayout.library/LT_LabelWidth NAME LT_LabelWidth -- Calculate the width of a string according to the user interface font used. SYNOPSIS Width = LT_LabelWidth(Handle,Label); D0 A0 A1 LONG LT_LabelWidth(LayoutHandle *,STRPTR); FUNCTION This routine calculates the width of strings in terms of pixels according to the user interface font associated with the LayoutHandle. INPUTS Handle - Pointer to LayoutHandle structure. RESULT Width - Width of the text string in pixels. gtlayout.library/LT_LayoutMenusA gtlayout.library/LT_LayoutMenusA NAME LT_LayoutMenusA -- Create a menu according to a template. SYNOPSIS Menu = LT_LayoutMenusA(Handle,Template,Tags); D0 A0 A1 A2 struct Menu *LT_LayoutMenusA(LayoutHandle *,struct NewMenu *,struct TagItem *); Menu = LT_LayoutMenus(Handle,Template,...); struct Menu *LT_LayoutMenus(LayoutHandle *,struct NewMenu *,...); FUNCTION Unlike the corresponding routines in gadtools.library LT_LayoutMenusA() will both create and layout a menu. Also included is locale support. INPUTS Handle - Pointer to LayoutHandle structure. Template - Address of a ready-to-use NewMenu table to create the menu from. Tags - Tagitem list to control menu attributes TAGS LAMN_FirstLabel (LONG) - Locale ID of the first string to use as a menu title/item/subitem label. This tag works in conjunction with LA_LastLabel. LAMN_LastLabel (LONG) - Locale ID of the last string to use as a menu title/item/subitem label. This tag works in conjunction with LA_FirstLabel. The code will loop through FirstLabel..LastLabel and assign the corresponding locale text for each ID to the NewMenu.nm_Label entries. Labels which are already initialized with NM_BARLABEL are skipped. LAMN_LabelTable (LONG *) - Pointer to an array of IDs to use for building the menu labels. This requires that a locale hook is provided with the layout handle. The array is terminated by -1. NOTES If you created the LayoutHandle with the LH_MenuGlyphs,TRUE attribute, the menu will use the scaled menu glyphs. RESULT Menu - Pointer to a Menu structure. You can free this using gadtools.library/FreeMenus(). gtlayout.library/LT_LevelWidth gtlayout.library/LT_LevelWidth NAME LT_LevelWidth -- Determine the maximum width of a SLIDER_KIND level string. SYNOPSIS Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth, D0 A0 A1 A2 D0 D1 A3 MaxLen,FullCheck); A5 D2 LONG LT_LevelWidth(LayoutHandle *,STRPTR, LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *, LONG *,BOOL); FUNCTION In order to make room for the level text displayed by a SLIDER_KIND object one needs to know how much space the longest level string will occupy. Otherwise, the level text may overwrite the gadget label text or the slider container. This routine will rattle through all possible slider settings (as given via the Min and the Max level values) and determine the longest label string according to the font used. INPUTS Handle - Pointer to a LayoutHandle structure, as returned by a call to LT_CreateHandleTags(). FormatString - The sprintf() style formatting string to be used to format the slider level settings into text. This is the same string you would pass in via the GTSL_LevelFormat tag when creating the slider object. Default: "%lD" for systems which have locale.library installed, "%ld" otherwise. DispFunc - A pointer to the function to filter the slider level values. The result of this function will then be used to format a string into the slider level text. This is the same parameter you would pass in via the GTSL_DispFunc tag when creating the slider object. NOTE: the routine will be called with a NULL Gadget parameter, make sure your code will handle this nicely. Default: no display function Min - The smallest value the slider can be set to. This is same value you would pass in via GTSL_Min when creating the slider object. Max - The largest value the slider can be set to. This is same value you would pass in via GTSL_Max when creating the slider object. MaxWidth - Pointer to a place to store the width of the longest level string in pixels. If you pass in NULL instead of the address of a variable no harm will be done. MaxLen - Pointer to a place to store the length of the longest level string in characters. If you pass in NULL instead of the address of a variable no harm will be done. FullCheck - TRUE will cause the code to rattle through all possible slider settings, starting from the minimum value, ending at the maximum value. While this may be a good idea for a display function to map slider levels to text strings of varying length it might be a problem when it comes to display a range of numbers from 1 to 40,000: the code will loop through 40,000 iterations trying to find the longest string. FALSE will cause the code to calculate the longest level string based only on the minimum and the maximum value to check. While this is certainly a good a idea when it comes to display a range of numbers from 1 to 40,000 as only two values will be checked the code may fail to produce accurate results for sliders using display functions mapping slider levels to strings. RESULT Index - The slider level which gives the longest level string. gtlayout.library/LT_LockWindow gtlayout.library/LT_LockWindow NAME LT_LockWindow -- Block user access to a window. SYNOPSIS LT_LockWindow(Window); A0 VOID LT_LockWindow(struct Window *); FUNCTION The window will get a wait mouse pointer attached and a blank Requester, preventing any user gadgets from getting used. The window minimum and maximum sizes are set to the current window size so the user will be unable to resize the window or click on the zoom gadget. This routine nests, multiple calls to LT_LockWindow() using the same window will increment a usage counter, so exactly the same number of calls to LT_UnlockWindow() will be required to unlock the window. INPUTS Window - Pointer to window structure. RESULT none NOTES Do not close the window you have locked unless all the outstanding locks are freed or memory will be lost which can never be reclaimed. gtlayout.library/LT_NewA gtlayout.library/LT_NewA NAME LT_NewA -- Add a new object to the user interface tree. SYNOPSIS LT_NewA(Handle,Tags); A0 A1 VOID LT_NewA(LayoutHandle *,struct TagItem *); LT_New(Handle,...); VOID LT_New(LayoutHandle *,...); FUNCTION LT_NewA() is the routine you use to build the user interface, you give layout directions, design groups, etc. and finally call LT_BuildA() to turn these specifications into a window. INPUTS Handle - Pointer to LayoutHandle structure. TAGS This routine will accept almost all create-time tag items gadtools.library/CreateGadget will handle. In addition to this there are a bunch of extra gadget objects and extra tag items supported: All object types: LA_Type (LONG) - Type of the object to create, must be one of the following: TEXT_KIND VERTICAL_KIND HORIZONTAL_KIND END_KIND FRAME_KIND BOX_KIND SLIDER_KIND LISTVIEW_KIND INTEGER_KIND STRING_KIND PASSWORD_KIND PALETTE_KIND BUTTON_KIND CHECKBOX_KIND NUMBER_KIND GAUGE_KIND CYCLE_KIND MX_KIND XBAR_KIND YBAR_KIND FRACTION_KIND TAPEDECK_KIND LEVEL_KIND LA_LabelText (STRPTR) - The object label text to use. LA_LabelID (LONG) - The locale text ID of the string to use as the object label text. NOTE: LT_NewA() will fail if you forget to select a hook with LH_LocaleHook at LT_CreateHandleTagList. LA_ID (LONG) - The gadget ID to use for this object. NOTE: User ID values *MUST* be greater than 0, negative values are reserved for internal use. LA_Chars (LONG) - The width of this object measured in characters. If each character of the user interface font is 8 pixels wide an object with LA_Chars set to 10 will usually be 80 pixels wide. LA_LabelChars (LONG) - This forces the internal gadget label width the layout engine calculates during the layout pass to a specific value. Note: this does not work well with all objects. (requires gtlayout.library v9 or higher) LA_LabelPlace (LONG) - Where to place the gadget label. Not all objects will support all label positions: PLACE_LEFT - Place label text left of object PLACE_RIGHT - Place label text right of object PLACE_ABOVE - Place label text above object PLACE_IN - Place label text in object PLACE_BELOW - Place label text below object LA_ExtraSpace (BOOL) - Add extra vertical/horizontal space before this object. Default: FALSE LA_ExtraFat (BOOL) - Make this object a bit larger than its usual size. Default: FALSE LA_NoKey (BOOL) - Don't let the user interface choose a keyboard shortcut for this object. Default: FALSE LA_HighLabel (BOOL) - Use highlight pen when rendering the gadget label text. Default: FALSE LA_BYTE (BYTE *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_UBYTE (UBYTE *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_WORD (WORD *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_UWORD (UWORD *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_BOOL (BOOL *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_LONG (LONG *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_ULONG (ULONG *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_STRPTR (STRPTR) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. LA_FRACTION (FRACTION *) - Pointer to the variable that holds the "current value" of the object. The layout engine will retrieve this value initially during the creation of the object and maintain it during its lifespan. This means you do not need to worry about checking the state of the object, the user interface layout engine will do it for you. TEXT_KIND: LATX_Picker (BOOL) - Attach a `select' button to the right hand side of the text display. Default: FALSE VERTICAL_KIND (group to align objects vertically): HORIZONTAL_KIND (group to align objects horizontally): LAGR_Spread (BOOL) - Place all objects in this group with roughly the same amount of space between them. Default: FALSE LAGR_SameSize (BOOL) - Make all objects in this group the same size (for vertical groups: the same height, for horizontal groups: the same width). Default: FALSE LAGR_LastAttributes (BOOL) - Try to copy the size of the previous group for this new group. May not work if this group turns out to be larger than the previous group. Default: FALSE LAGR_ActivePage (LONG) - Organize all child groups as pages which can be flipped through using LT_SetAttributes(). You need to specify the number of the first page to display, starting from 0. NOTE: Specifying this tag actually enables the paging feature. If you omit this tag calls to flip to a specific page will fail. Default: No paging LAGR_Frame (BOOL) - Draw a recessed frame around this group, even if there is no group label. (requires gtlayout.library v7 or higher) FRAME_KIND (fixed size general purpose display, you may render into it): LAFR_InnerWidth (LONG) - Inner width of the display box. LAFR_InnerHeight (LONG) - Inner height of the display box. LAFR_DrawBox (BOOL) - Draw a recessed bevel box around the display box. Default: FALSE LAFR_RefreshHook (struct Hook *) - Hook to call when refreshing/redrawing this object. See gtlayout.h for more information. (requires gtlayout.library v9 or higher) XBAR_KIND (horizontal separator bar): LAXB_FullSize (BOOL) - Make this separator bar span the entire window width. BOX_KIND (multiline text display): LABX_Labels (STRPTR *) - The label texts to display on the right hand side of the box. Terminate this array with NULL. LABX_Lines (STRPTR *) - The text to display in the box. Terminate this array with NULL. LABX_Rows (LONG) - The width of this object in characters. The layout routine will try to make sure that the given number of characters will fit into a single line of text in this box. This may be a problem with proportional spaced fonts. LABX_AlignText (LONG) - Controls how text is aligned in box lines: ALIGNTEXT_LEFT - Align text to the left edge ALIGNTEXT_CENTERED - Centre the text ALIGNTEXT_RIGHT - Align text to the right edge ALIGNTEXT_PAD - Pad text lines Default: ALIGNTEXT_LEFT LABX_DrawBox (BOOL) - Draw a recessed bevel box around the text box. Default: FALSE LABX_FirstLabel (LONG) - Locale string ID of the first text to use as a box label. Works in conjunction with LABX_LastLabel. LABX_LastLabel (LONG) - Locale string ID of the last text to use as a box label. Works in conjunction with LABX_FirstLabel. When building the interface the code will loop from FirstLabel..LastLabel, look up the corresponding locale strings and use the data to make up the label text to appear at the right hand side of the box. LABX_LabelTable (LONG *) - Pointer to an array of IDs to use for building the box labels. This requires that a locale hook is provided with the layout handle. The array is terminated by -1. LABX_ReserveSpace (BOOL) - Allocate extra memory to hold the contents of the lines displayed. This avoids nasty side-effects when refreshing this object. Default: FALSE FRACTION_KIND: LAFC_MaxChars (LONG) - Maximum number of characters to fit into the entry field. Default: 16 LAFC_Number (FIXED) - Fixed point number to use for this object. Default: 0.0 LAFC_LastGadget (BOOL) - When cycling through the text entry fields, stop cycling after leaving this object. Default: FALSE LAFC_Min (FIXED) - Minimum value allowed for this object. LAFC_Max (FIXED) - Maximum value allowed for this object. LAFC_HistoryLines (LONG) - Maximum number of entries to keep as a backlog. Default: 0 LAFC_HistoryHook (struct Hook *) - Hook code to call when entering a number into the backlog. See gtlayout.h for more information. Default: NULL SLIDER_KIND: LASL_FullCheck: TRUE will cause the code to rattle through all possible slider settings, starting from the minimum value, ending at the maximum value. While this may be a good idea for a display function to map slider levels to text strings of varying length it might be a problem when it comes to display a range of numbers from 1 to 40,000: the code will loop through 40,000 iterations trying to find the longest string. FALSE will cause the code to calculate the longest level string based only on the minimum and the maximum value to check. While this is certainly a good a idea when it comes to display a range of numbers from 1 to 40,000 as only two values will be checked the code may fail to produce accurate results for sliders using display functions mapping slider levels to strings. Default: TRUE LEVEL_KIND: All tags are supported which SLIDER_KIND supports. The gadget level display however, can only be aligned to the left border. LISTVIEW_KIND: LALV_ExtraLabels (STRPTR *) - Place extra line labels at the right of the box. Terminate this array with NULL. LALV_Labels (STRPTR *) - The labels to display inside the box, you can pass this array of strings in rather than passing an initialized List of text via GTLV_Labels. Terminate this array with NULL. LALV_CursorKey (BOOL) - Let the user operate this listview using the cursor keys. NOTE: there can be only one single listview per window to sport this feature. Default: FALSE LALV_Lines (LONG) - The number of text lines this listview is to display. LALV_Link (LONG) - The Gadget ID of a string gadget to attach to this listview. NOTE: you need to add the Gadget in question before you add the listview to refer to it or the layout routine will get confused. Passing the value NIL_LINK will create a listview which displays the currently selected item, otherwise you will get a read-only list. LALV_FirstLabel (LONG) - Locale string ID of the first text to use as a list label. Works in conjunction with LALV_LastLabel. LALV_LastLabel (LONG) - Locale string ID of the last text to use as a list label. Works in conjunction with LALV_FirstLabel. When building the interface the code will loop from FirstLabel..LastLabel, look up the corresponding locale strings and use the data to make up the label text to appear in the list. LALV_LabelTable (LONG *) - Pointer to an array of IDs to use for building the listview contents. This requires that a locale hook is provided with the layout handle. The array is terminated by -1. LALV_MaxGrowX (LONG) - Maximum width of this object measured in characters. When the first layout pass is finished and there is still enough space left to make the listview wider, the width is increased until it hits the limit specified using this tag. NOTE: there can be only one single listview per window to sport this feature. Default: 0 LALV_MaxGrowY (LONG) - Maximum height of this object measured in lines. When the first layout pass is finished and there is till enough space left to make the listview higher, the height is increased until it hits the limit specified using this tag. NOTE: there can be only one single listview per window to sport this feature. Default: 0 LALV_ResizeX (BOOL) - Makes this listview resizable in the horizontal direction, attaches a sizing gadget to the window to open and handles window resize operations automatically. (requires gtlayout.library v9 or higher) NOTE: there can be only one single listview per window to sport this feature. Also listen to IDCMP_CLOSEWINDOW events which may be generated if the layout engine runs out of memory when rebuilding the user interface. Default: FALSE LALV_ResizeY (BOOL) - Makes this listview resizable in the vertical direction, attaches a sizing gadget to the window to open and handles window resize operations automatically. (requires gtlayout.library v9 or higher) NOTE: there can be only one single listview per window to sport this feature. Also listen to IDCMP_CLOSEWINDOW events which may be generated if the layout engine runs out of memory when rebuilding the user interface. Default: FALSE LALV_MinChars (WORD) - Minimum width for this object, measured in characters. Used in conjunction with LALV_ResizeX. (requires gtlayout.library v9 or higher) LALV_MinLines (WORD) - Minimum height for this object, measured in lines. Used in conjunction with LALV_ResizeY. (requires gtlayout.library v9 or higher) LALV_LockSize (BOOL) - After doing the initial layout for this object, do not adapt its size again during subsequent layouts. This is particularly useful if you have a LISTVIEW_KIND object in a paged group and keep adding new entries to the list. You need to specify an object width using LA_Chars, otherwise the layout engine may make it not wide enough to display any entries. (requires gtlayout.library v8 or higher) LALV_FlushLabelLeft (BOOL) - For a gadget label placed above the listview align the text to the left edge of the view. (requires gtlayout.library v9 or higher) INTEGER_KIND: LAIN_LastGadget (BOOL) - Pressing return with this gadget active will stop activating the next following string gadget type if TRUE is passed. Default: FALSE LAIN_Min (LONG) - Minimum accepted numeric value. Default: -2147483647 LAIN_Max (LONG) - Maximum accepted numeric value. Default: 2147483647 LAIN_UseIncrementers (BOOL) - Use TRUE to add incrementer arrow buttons to the right of the numeric entry field. These buttons will let you cycle through a set of numbers to be displayed in the numeric entry field. Default: FALSE LAIN_HistoryLines (LONG) - Number of numbers entered to keep as a backlog. Default: 0 LAIN_HistoryHook (struct Hook *) - Hook code to call when entering a number into the backlog. See gtlayout.h for more information. Default: NULL LAIN_IncrementerHook (struct Hook *) - Hook code to call when cycling through numeric values. See gtlayout.h for more information. Default: NULL STRING_KIND: LAST_LastGadget (BOOL) - Pressing return with this gadget active will stop activating the next following string gadget type if TRUE is passed. Default: FALSE LAST_Link (LONG) - Gadget ID of the listview to attach this string gadget to. NOTE: you need to add the string gadget before you add the listview to refer to it or the layout routine will get confused. LAST_Picker (BOOL) - Attach a `select' button to the right hand side of the string gadget. Default: FALSE LAST_HistoryLines (LONG) - Number of lines to keep as a backlog. Default: 0 LAST_HistoryHook (struct Hook *) - Hook code to call when entering a line into the backlog. See gtlayout.h for more information. Default: NULL PASSWORD_KIND (string gadget type which does not display its contents): LAPW_LastGadget (BOOL) - Pressing return with this gadget active will stop activating the next following string gadget type if TRUE is passed. Default: FALSE LAPA_HistoryLines (LONG) - Number of lines to keep as a backlog. Default: 0 LAPA_HistoryHook (struct Hook *) - Hook code to call when entering a line into the backlog. See gtlayout.h for more information. Default: NULL This object type accepts all the GTST_#? tag items. PALETTE_KIND: LAPA_SmallPalette (BOOL) - Make the palette display a bit smaller than usual. Default: FALSE LAPA_Lines (LONG) - Number of lines the palette display should cover. Default: No preference BUTTON_KIND: LABT_ReturnKey (BOOL) - Let the user operate this button by pressing the return key. There will be a recessed bevel box drawn around the button to indicate this special feature. NOTE: there can be only one single button per window to sport this feature. Default: FALSE LABT_EscKey (BOOL) - Let the user operate this button by pressing the Escape key. NOTE: there can be only one single button per window to use this feature. Default: FALSE LABT_ExtraFat (BOOL) - Make this button a bit larger than usual. Default: FALSE GAUGE_KIND (general purpose progress report display): LAGA_Percent (LONG) - Indicator position, can range from 0..100. Default: 0 LAGA_InfoLength (LONG) - Maximum number of characters to reserve for text printed in the gauge display. Default: 0 LAGA_InfoText (STRPTR) - Text to print in the gauge display. CYCLE_KIND: LACY_FirstLabel (LONG) - Locale string ID of the first text to use as a label. Works in conjunction with LACY_LastLabel. LACY_LastLabel (LONG) - Locale string ID of the last text to use as a label. Works in conjunction with LACY_FirstLabel. When building the interface the code will loop from FirstLabel..LastLabel, look up the corresponding locale strings and use the data to make up the label text. LACY_LabelTable (LONG *) - Pointer to an array of IDs to use for building the cycle labels. This requires that a locale hook is provided with the layout handle. The array is terminated by -1. LACY_TabKey (BOOL) - Connect this object to the tabulator key. Press [Tab] to cycle to the next entry, [Shift][Tab] to cycle to the previous entry. NOTE: there can be only one single button per window to use this feature. Default: FALSE (requires gtlayout.library v9 or higher) LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object which will be set to the gadget's current setting. (requires gtlayout.library v7 or higher) NOTE: Listen to IDCMP_CLOSEWINDOW events which may be generated if the layout engine runs out of memory when rebuilding the user interface. MX_KIND: LAMX_FirstLabel (LONG) - Locale string ID of the first text to use as a label. Works in conjunction with LAMX_LastLabel. LAMX_LastLabel (LONG) - Locale string ID of the last text to use as a label. Works in conjunction with LAMX_FirstLabel. When building the interface the code will loop from FirstLabel..LastLabel, look up the corresponding locale strings and use the data to make up the label text. LAMX_LabelTable (LONG *) - Pointer to an array of IDs to use for building the radio labels. This requires that a locale hook is provided with the layout handle. The array is terminated by -1. LAMX_TabKey (BOOL) - Connect this object to the tabulator key. Press [Tab] to cycle to the next entry, [Shift][Tab] to cycle to the previous entry. NOTE: there can be only one single button per window to use this feature. Default: FALSE (requires gtlayout.library v9 or higher) LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object which will be set to the gadget's current setting. (requires gtlayout.library v7 or higher) NOTE: Listen to IDCMP_CLOSEWINDOW events which may be generated if the layout engine runs out of memory when rebuilding the user interface. SCROLLER_KIND: LASC_Thin (BOOL) - Make the scroller a bit thinner than usual. Default: FALSE TAPEDECK_KIND: LATD_ButtonType (LONG) - Select the image to display in the button, must be one of the following: DTBT_BACKWARD "<<" Symbol DTBT_FORWARD ">>" Symbol DTBT_PREVIOUS "|<" Symbol DTBT_NEXT ">|" Symbol DTBT_STOP Stop symbol (filled square) DTBT_PAUSE Pause symbol (broken square) DTBT_RECORD Record symbol (filled circle) DTBT_REWIND "<" symbol DTBT_EJECT Eject symbol (broken upward pointing arrow) DTBT_PLAY ">" symbol LATD_Toggle (BOOL) - Make this object a toggle-select button. Default: FALSE LATD_Pressed (BOOL) - Make this button appear to be pressed. NOTE: requires "LATD_Toggle,TRUE" attribute. Default: FALSE LATD_Smaller (BOOL) - Make this button a bit smaller than usual. Default: FALSE RESULT none gtlayout.library/LT_PressButton gtlayout.library/LT_PressButton NAME LT_PressButton -- Highlight a button so it looks as if the user has selected it. SYNOPSIS LT_PressButton(Handle,ID); A0 D0 VOID LT_PressButton(LayoutHandle *,LONG); FUNCTION You can provide visual feedback for BUTTON_KIND objects by calling this routine. They will briefly appear to be selected and then fall back to their original states. INPUTS Handle - Pointer to LayoutHandle structure ID - ID of button object to highlight RESULT none gtlayout.library/LT_RebuildTagList gtlayout.library/LT_RebuildTagList NAME LT_RebuildTagList -- Rebuild the user interface after modifying it. SYNOPSIS Success = LT_RebuildTagList(Handle,Clear,TagList); D0 A0 D0 A1 BOOL LT_RebuildTagList(LayoutHandle *,BOOL,struct TagItem *); Success = LT_RebuildTags(Handle,Clear,...); BOOL LT_RebuildTags(LayoutHandle *,BOOL,...); FUNCTION Certain aspects of the user interface can be changed at run time, such as button labels. This routine will let you rebuild the interface based upon the data supplied at creation time and your subsequent changes. Before you make any vital changes, it is recommended to lock the window using LT_LockWindow() in order to avoid clashes with the Intuition and GadTools subsystems. INPUTS Handle - Pointer to LayoutHandle structure. Clear - Pass in TRUE if you wish to have the window contents cleared before they are rebuild. This will introduce some visual hashing. TagList - Attributes controlling the layout process. RESULT Success - TRUE indicates that the interface was rebuilt, FALSE indicates trouble; it is recommended to call LT_DeleteHandle() on your LayoutHandle as soon as possible as the previous operation may have left the user interface in an inoperable state. TAGS LAWN_Bounds (struct IBox *) - Boundaries in which the window should be centered. LAWN_ExtraWidth (LONG) - Extra space to add to the window width. LAWN_ExtraHeight (LONG) - Extra height to add to the window height. gtlayout.library/LT_ReplyIMsg gtlayout.library/LT_ReplyIMsg NAME LT_ReplyIMsg -- Dispose of an IntuiMessage received SYNOPSIS LT_ReplyIMsg(IntuiMessage); A0 VOID LT_ReplyIMsg(struct IntuiMessage *); FUNCTION This routine complements LT_GetIMsg(). INPUTS IntuiMessage - Pointer to IntuiMessage structure, passing NULL is harmless. NOTES Only pass IntuiMessages you received via LT_GetIMsg, or things will get tough. RESULT none SEE ALSO gtlayout.library/LT_GetIMsg gtlayout.library/LT_SetAttributesA gtlayout.library/LT_SetAttributesA NAME LT_SetAttributesA -- Change object attributes SYNOPSIS LT_SetAttributesA(Handle,ID,Tags); A0 D0 A1 VOID LT_SetAttributes(LayoutHandle *,LONG,struct TagItem *); LT_SetAttributes(Handle,ID,...); VOID LT_SetAttributes(LayoutHandle *,LONG,...); FUNCTION This routine passes the tag item list it gets directly over to GT_SetGadgetAttrsA(), so any tag items valid for gadtools.library can be used here as well. Some filtering may be done in order to stop objects from getting redrawn if this is not absolutely necessary. INPUTS Handle - Pointer to LayoutHandle. ID - ID number of the object to change. This is the same value you passed via LA_ID to LT_New() when you created this object. Tags - Attributes controlling object states. TAGS All gadtools.library tags are allowed, but not all are supported. In addition to these tags a few additional tag values are supported: LH_AutoActivate (BOOL) - Set to TRUE if you want the interface to always keep a string gadget active if possible. Hitting the return key will then cause the next following string gadget to get activated, either cycling through all the string gadgets available or stopping at the next string gadget to have the LAST_LastGadget attribute set. LH_UserData (APTR) - Store user specific data in the LayoutHandle->UserData entry. (requires gtlayout.library v9 or higher) LH_LocaleHook (struct Hook *) - The hook to call when locale string IDs are to be mapped to strings. The hook function is called with the following parameters: String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle, D0 A0 A2 LONG ID) A1 The function is to look up the string associated with the ID passed in and return the string. LH_ExitFlush (BOOL) - When the LayoutHandle is finally disposed of with LT_DeleteHandle() all variables maintained by the input handling code will be flushed. For example, if you would use the LA_STRPTR tag for STRING_KIND objects the last string gadget contents would be copied into the buffer pointed to by LA_STRPTR. If you do not want to use this feature, disable it with "LH_ExitFlush,FALSE". Default: TRUE (requires gtlayout.library v9 or higher) GAUGE_KIND: LAGA_Percent (LONG) - Percentage of the gauge to fill. LAGA_InfoText (STRPTR) - Text to be printed within the gauge display, such as a percentage number. BOX_KIND: LABX_Index (LONG) - The number of the line to change, this tag works in conjunction with the LABX_Text tag. LABX_Text (STRPTR) - The text to put into the line indicated by the LABX_Index tag. LABX_Lines (STRPTR *) - The text to set for the box contents, terminate the text array with NULL. HORIZONTAL_KIND: VERTICAL_KIND: LAGR_ActivePage (LONG) - Index number of page to display witthin the group. NOTE: requires that this group was created with the LAGR_ActivePage attribute set. FRACTION_KIND: LAFC_Number (FIXED) - Fixed point number to use LAFC_Min (FIXED) - Minimum allowed value for this object. LAFC_Max (FIXED) - Maximum allowed value for this object. INTEGER_KIND: LAIN_Min (LONG) - Minimum allowed value for this object. LAIN_Max (LONG) - Maximum allowed value for this object. PASSWORD_KIND: LAPW_String (STRPTR) - Secret text to use STRING_KIND: LAST_CursorPosition (LONG) - Repositions the cursor, pass -1 to move it to the end of the string. (requires gtlayout.library v7 or higher) TAPEDECK_KIND: LATD_Pressed (BOOL) - TRUE to make this button shown as pressed, FALSE to show it in depressed state. All objects: LA_LabelText (STRPTR) - New gadget label text to use. LA_LabelID (LONG) - Locale text ID to use for this object. RESULT none gtlayout.library/LT_ShowWindow gtlayout.library/LT_ShowWindow NAME LT_ShowWindow -- Make a window visible SYNOPSIS LT_ShowWindow(Handle,Activate); A0 A1 VOID LT_ShowWindow(LayoutHandle *,BOOL); FUNCTION The window attached to a LayoutHandle is made visible, this involves bringing it to the front, bringing the screen to the front the window resides on, unzooming the window and also moving the visible part of an autoscrolling screen. INPUTS Window - Pointer to Window structure. Activate - If TRUE the window will be activated as soon as it has been brought to the front. The arguments are passed in A0 and A1, this is *not* a typo. RESULT none gtlayout.library/LT_String2Fixed gtlayout.library/LT_String2Fixed NAME LT_String2Fixed -- Convert an ASCII string into a fixed-point numeric value. SYNOPSIS Fixed = LT_String2Fixed(String) D0 A0 FIXED LT_String2Fixed(STRPTR); FUNCTION This routine complements LT_Fixed2String, it implements a service similar to atof() in converting an ASCII string into a fixed-point number. INPUTS String - Pointer to null-terminated string. RESULT Fixed - Fixed-point number; will be 0.0 if non-numeric characters are found in the input string. NOTES The decimal point to look for will be taken from the current locale settings. If locale.library is not installed, the `.' character will be used instead. gtlayout.library/LT_UnlockWindow gtlayout.library/LT_UnlockWindow NAME LT_UnlockWindow -- The complement to LT_LockWindow(). SYNOPSIS LT_UnlockWindow(Window); A0 VOID LT_UnlockWindow(struct Window *); FUNCTION This routine unlocks a window locked using LT_LockWindow, freeing allocated memory, restoring the window characteristics to their original values. INPUTS Window - Pointer to window structure. RESULT none gtlayout.library/LT_UpdateStrings gtlayout.library/LT_UpdateStrings NAME LT_UpdateStrings -- Make sure all visible string buffer contents get written into storage. (requires gtlayout.library v9 or higher) SYNOPSIS LT_UpdateStrings(LayoutHandle); A0 VOID LT_UpdateStrings(struct LayoutHandle *); FUNCTION The user can terminate input into a string gadget or an object derived from a string gadget by various means. They all have in common that the application receives no notification that the string gadget contents have changed. This is particularly nasty with objects which make use of LA_STRPTR or other tags. Using LT_UpdateStrings() you can force all visible string gadget objects to hand over their contents to the internal buffers. Do this before you eventually exit your input loop. INPUTS LayoutHandle - Pointer to LayoutHandle structure. RESULT none