AmigActive 23/AACD 23.iso/AACD/Programming/gtlayout/Doc/gtlayout.doc

Text File | 1999-10-11 | 132.5 KB | 3,992 lines

TABLE OF CONTENTS

gtlayout.library/--background--
gtlayout.library/--version--
gtlayout.library/LT_Activate
gtlayout.library/LT_BeginRefresh
gtlayout.library/LT_BuildA
gtlayout.library/LT_CatchUpRefresh
gtlayout.library/LT_CreateHandleTagList
gtlayout.library/LT_DeleteHandle
gtlayout.library/LT_DeleteWindowLock
gtlayout.library/LT_DisposeMenu
gtlayout.library/LT_EndGroup
gtlayout.library/LT_EndRefresh
gtlayout.library/LT_Exit
gtlayout.library/LT_FindMenuCommand
gtlayout.library/LT_GetAttributesA
gtlayout.library/LT_GetCode
gtlayout.library/LT_GetIMsg
gtlayout.library/LT_GetMenuItem
gtlayout.library/LT_GetWindowUserData
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_MenuControlTagList
gtlayout.library/LT_NewA
gtlayout.library/LT_NewLevelWidth
gtlayout.library/LT_NewMenuTagList
gtlayout.library/LT_NewMenuTemplate
gtlayout.library/LT_PressButton
gtlayout.library/LT_RebuildTagList
gtlayout.library/LT_Redraw
gtlayout.library/LT_Refresh
gtlayout.library/LT_ReplyIMsg
gtlayout.library/LT_SetAttributesA
gtlayout.library/LT_ShowWindow
gtlayout.library/LT_UnlockWindow
gtlayout.library/LT_UpdateStrings
gtlayout.library/--background--               gtlayout.library/--background--

   NOTES
    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 80K-100K 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
    tested how much stack they might require in certain cases,
    but I recommend that you don't overuse the grouping feature.
    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 for link library version

    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();    // only for link library version
       :
       :
          LT_CreateHandleTags();
             LT_New();
             :
             :
             LT_New();
                LT_Build();
                   LT_HandleInput();
          LT_DeleteHandle();
       :
       :
       LT_Exit();    // only for link library version

    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,
          LAHN_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 called 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
       PALETTE_KIND

          The user pressed the `select' button which belongs
          to this gadget. The MsgGadget pointer indicates the
          STRING_KIND/TEXT_KIND/PALETTE_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 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. I owe Martin
    much for the ideas he put into the library.

    Kai Iske, Christoph Feck, Stefan Becker, Michael Barsoom, Sven Stullich
    and Mark Ritter helped to iron out the remaining bugs and piled up bug
    reports and enhancement requests.

gtlayout.library/--version--                     gtlayout.library/--version--

   NOTES
    This document describes gtlayout.library v5.12 or higher. Do not assume that
    previous library releases support the same features.

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

   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.

    To make it easier to distinguish between different handles that
    share the same Window->UserPort, the Window->UserData pointer
    will point to the LayoutHandle that created it (V13).

        NOTE: Earlier library releases did not support this feature,
            so be prepared to deal with Window->UserData == NULL.

   INPUTS
    Handle - Pointer to a LayoutHandle structure.

    Tags - Pointer to TagItem list controlling window
        and layout attributes.


    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_MenuTemplate (struct NewMenu *) - A list of filled-in
        NewMenu structures which will get passed straight through
        to LT_NewMenuTemplate(). If a menu could be created, it will
        be attached to the window. LT_DeleteHandle() will then later
        automatically dispose of the menu. Please note that the window
        may fail to open due to the menu layout going wrong. Separate
        calls to LT_NewMenuTemplate() and LT_Build() may be a better
        approach since it is easier to find out which process went
        wrong. You will find a pointer to the menu attached to the
        LayoutHandle in LayoutHandle->Menu. Please note that this
        entry only exists in LayoutHandles created by gtlayout.library
        v13 or higher. (V13)

            NOTE: This tag effectively overrides LAWN_Menu.

    LAWN_MenuTags (struct TagItem *) - A list of TagItems which
        will get passed straight through to LT_NewMenuTagList().
        Even if you don't ask for it, LT_Build() will pass
        "LAMN_Handle,<Handle>" in for you, so any additional tags
        specifying screen, fonts, etc. will be overridden. If a menu
        could be created, it will be attached to the window.
        LT_DeleteHandle() will then later automatically dispose of the
        menu. Please note that the window may fail to open due to the
        menu layout going wrong. Separate calls to LT_NewMenuTagList()
        and LT_Build() may be a better approach since it is easier to
        find out which process went wrong. You will find a pointer to the
        menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
        that this entry only exists in LayoutHandles created by
        gtlayout.library v13 or higher. (V13)

            NOTE: This tag effectively overrides LAWN_Menu and has
                  precedence over LAWN_MenuTemplate.

    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.

    LAWN_FlushLeft (BOOL) - Add no horizontal space surrounding the
        objects the windows will hold. (V10)

    LAWN_FlushTop (BOOL) - Add no vertical space surrounding the
        objects the windows will hold. (V10)

    LAWN_Show (BOOL) - Make the window visible when it is opened;
        this may involve depth-arranging screens. (V10)
           Default: FALSE

    LAWN_NoInitialRefresh (BOOL) - If set to TRUE, adds the
        gadgets, but does not draw the window imagery. You need
        to draw them later by calling gtlayout.library/LT_Refresh.
        Default: FALSE

    LAWN_LimitWidth (UWORD) - Limit the width of the window to this
        value. (V35)

    LAWN_LimitHeight (UWORD) - Limit the height of the window to this
        value. (V35)

    LAWN_UserData (APTR) - Store this pointer with the Window information.
        you can later retrieve it with the LT_GetWindowUserData()
        call (V39).

   RESULT
    Window - Pointer to a Window structure.

   SEE ALSO
       gtlayout.library/LT_Refresh
       gtlayout.library/LT_GetWindowUserData
       intuition.library/OpenWindow
       intuition.library/OpenWindowTagList

gtlayout.library/LT_CatchUpRefresh         gtlayout.library/LT_CatchUpRefresh

   NAME
    LT_CatchUpRefresh -- Repair the display after missing the
                         Window refresh message (V34).

   SYNOPSIS
    LT_CatchUpRefresh(Handle)
                        A0

    VOID LT_CatchUpRefresh(LayoutHandle *);

   FUNCTION
    In case an application missed an IDCMP_REFRESHWINDOW event
    the display may be damaged and in need of repair. This can
    happen if the ASL requester is attached to the window,
    sharing its IDCMP with the window. Any refresh events will then
    go straight to nil. Call this routine if you believe that
    you missed a refresh event. The display will be repaired only
    if it is in need of repair, so there is no harm in calling it
    if not actually necessary.

   INPUTS
    Handle - Pointer to a LayoutHandle structure.

   RESULT
    none

   SEE ALSO
    gtlayout.library/LT_BeginRefresh
    intuition.library/BeginRefresh
    intuition.library/EndRefresh

gtlayout.library/LT_CreateHandleTagListtlayout.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.


    Valid tags include:

    LAHN_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

    LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
        events. (V13)
        Default: TRUE

    LAHN_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.

    LAHN_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

    LAHN_TextAttr (struct TTextAttr *) - The text font to use when
        creating the gadgets and objects.
        Default: Screen->Font

    LAHN_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 LAHN_CloningPermitted tag controls whether the engine will
        actually try to open the custom screen or just return NULL
        when LT_Build fails.
        Default: TRUE

    LAHN_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

    LAHN_ExactClone (BOOL) - This tag works in conjunction with the
        LAHN_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 LAHN_ExactClone
        tag with a value of TRUE.
        Default: FALSE

    LAHN_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

    LAHN_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

    LAHN_BlockParent (BOOL) - This tag works in conjunction with the
        LAHN_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

    LAHN_SimpleClone (BOOL) - This tag works in conjunction with the
        LAHN_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

    LAHN_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 "LAHN_ExitFlush,FALSE". (V9)
        Default: TRUE

    LAHN_NoKeys (BOOL) - Use TRUE to tell the library not to pick
        keyboard shortcuts all on its own. This works like calling
        LT_New() for all objects with "LA_NoKey,TRUE,". (V26)

    LAHN_PubScreen (struct Screen *) - Pointer to public screen
        window is to open on. Must be locked and open until you call
        LT_Built().

    LAHN_PubScreenName (STRPTR) - Name of public screen to open window
        on. The library will try to lock the named screen as soon as
        you call LT_CreateHandle.

    LAHN_PubScreenFallBack (BOOL) - If the named public screen cannot
        be found and you ask for it, the library will lock the default
        public screen (default: TRUE).

    LAHN_TopGroupType (LONG) - Request that after creating the layout
        handle, a layout group should be added to it. This can be
        either a vertical or a horizontal group. You specify the type
        using VERTICAL_KIND or HORIZONTAL_KIND (default: don't add
        any group). (V45)

   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; passing NULL is
    harmless.

   RESULT
    none

gtlayout.library/LT_DisposeMenu               gtlayout.library/LT_DisposeMenu

   NAME
    LT_DisposeMenu -- Release storage space allocated by
                      LT_NewMenuTemplate or LT_NewMenuTagList (V11)

   SYNOPSIS
    LT_DisposeMenu(Menu)
                    A0

    VOID LT_DisposeMenu(struct Menu *);

   FUNCTION
    Menus and MenuItems allocated by LT_NewMenuTemplate or
    LT_NewMenuTagList are deallocated.

   INPUTS
    Menu - Pointer to Menu structure as returned by
        LT_NewMenuTemplate or LT_NewMenuTagList. Passing
        NULL is harmless.

   RESULT
    none

   SEE ALSO
    gtlayout.library/LT_NewMenuTagList
    gtlayout.library/LT_NewMenuTemplate

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

   SEE ALSO
    gtlayout.library/LT_New

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
    gtlayout.library/LT_BeginRefresh
    intuition.library/BeginRefresh
    intuition.library/EndRefresh

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 function is not present in the shared library, only
    in the link library. You need not and cannot invoke it in
    the shared library.

   SEE ALSO
    gtlayout.library/LT_Init

gtlayout.library/LT_FindMenuCommand       gtlayout.library/LT_FindMenuCommand

   NAME
    LT_FindMenuCommand -- Get the menu/submenu item associated
                          with a rawkey event (V11)

   SYNOPSIS
    Item = LT_FindMenuCommand(Menu,Code,Qualifier,Gadget)
     D0                        A0  D0       D0      A1

    struct MenuItem *LT_FindMenuCommand(struct Menu *,

                         UWORD,ULONG,struct Gadget *);

   FUNCTION
    With the IntuiMessage data copied from a type IDCMP_RAWKEY message
    tries to find the MenuItem the event referred to.

   INPUTS
    Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.

    Code - Value copied from IntuiMessage->Code

    Qualifier - Value copied from IntuiMessage->Qualifier

    Gadget - Value copied from IntuiMessage->IAddress

   RESULT
    Item - Pointer to the struct MenuItem * in question or NULL
        if none could be found

   SEE ALSO
    gtlayout.library/LT_NewMenuTagList

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.


    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. (V9)

    LA_Lines (LONG *) - Height of object measured in character
        heights. (V9)

    LA_LabelLeft (LONG *) - Left edge of label text. (V9)

    LA_LabelTop (LONG *) - Top edge of label text. (V9)

    LABO_Object (Object *) - Returns a pointer to the BOOPSI object
        the BOOPSI_KIND object is based upon. (V10)

            NOTE: Don't unlink the object or dispose of it or
                terrible things are bound to happen.

    LAST_CursorPosition (LONG *) - Current position of the cursor
        in STRING_KIND and FRACTION_KIND objects. (V

   RESULT
    The result depends on the object type:

        VERTICAL_KIND:
        HORIZONTAL_KIND:

            active page

        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

        POPUP_KIND:

            current LAPU_Active state

        TAB_KIND:

            current LATB_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

        BOOPSI_KIND:

            whatever the object thinks is its
            current value

        TEXTEDIT_KIND:

            pointer to current string

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

    LONG 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.

    LT_GetIMsg() will try its best to distinguish between
    different LayoutHandles sharing the same Window->UserPort.
    If it finds that the window the message was sent to is
    using a different LayoutHandle, it will switch to using
    this handle (V13).

   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_GetMenuItem               gtlayout.library/LT_GetMenuItem

   NAME
    LT_GetMenuItem -- Get the menu/submenu item associated with an ID (V11)

   SYNOPSIS
    Item = LT_GetMenuItem(Menu,ID)
     D0                    A0  D0

    struct MenuItem *LT_GetMenuItem(struct Menu *,ULONG);

   FUNCTION
    This routine scans through all menu items associated with the
    menu and returns a pointer to the item associated with the
    given ID value.

   INPUTS
    Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.

    ID - Unique ID of the item to find.

   RESULT
    Item - Pointer to the struct MenuItem * in question or NULL
        if none could be found

   SEE ALSO
    gtlayout.library/LT_NewMenuTagList

gtlayout.library/LT_GetWindowUserData   gtlayout.library/LT_GetWindowUserData

   NAME
    LT_GetWindowUserData -- Obtain user data information associated
        with a Window created by gtlayout.library/LT_Build (V39).

   SYNOPSIS
    Data = LT_GetWindowUserData(Window,DefaultValue);
      D0                         A0        A1

    APTR LT_GetWindowUserData(struct Window *,APTR);

   FUNCTION
    You can tell the build process to store user data with the Window
    it creates. This can be used as a replacement for the Window->UserData
    pointer information which gtlayout.library uses for itself. If the
    Window you pass to this routine was created by gtlayout.library/LT_Build
    you will receive the user data pointer you passed in, otherwise the
    given default value will be returned.

   INPUTS
    Window - Pointer to a Window created by gtlayout.library/LT_Build

   RESULT
    Data - The user data pointer you provided for gtlayout.library/LT_Build
        with the LAWN_UserData tag or the default value if no such pointer
        was provided or this Window was not created by
        gtlayout.library/LT_Build.

    DefaultValue - If the window was not created by gtlayout.library/LT_Build
        this is the value you will receive as the function result.

   SEE ALSO
       gtlayout.library/LT_Build

gtlayout.library/LT_HandleInput               gtlayout.library/LT_HandleInput

   NAME
    LT_HandleInput -- Filter IntuiMessage data.

   SYNOPSIS
    LT_HandleInput(Handle,Qualifier,Class,Code,Gadget);
                     A0      D0      A1    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.

   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.

   RESULT
    none

   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);
        }
    }

   NOTES
    For BOOPSI_KIND objects keystroke activation may lead to
    unexpected results. Your application will hear a IDCMP_GADGETUP
    event, the IntuiMessage->Code value will hold the ANSI key
    code of the key the user pressed.

    Do not call this routine before you have actually
    replied the IntuiMessage received or weird things
    may happen. This is not a suggestion, it's a threat.

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.

   NOTES
    This function is not present in the shared library, only
    in the link library. You need not and cannot invoke it in
    the shared library.

   SEE ALSO
    gtlayout.library/LT_Exit

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().

    You can pass multi-line label texts to this routine,
    it will calculate the maximum length of the single
    lines. (V12)

   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.

    You can pass multi-line label texts to this routine,
    it will calculate the maximum length of the single
    lines. (V12)

   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.

   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.

   NOTES
    Some compilers have trouble passing parameters in A5. In such
    a case it is recommended to use gtlayout.library/LT_NewLevelWidth
    instead.

   SEE ALSO
    gtlayout.library/LT_NewLevelWidth

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; passign NULL is harmless.

   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. Before you close the window,
    call gtlayout.library/LT_DeleteWindowLock.

   SEE ALSO
    gtlayout.library/LT_DeleteWindowLock

gtlayout.library/LT_MenuControlTagList gtlayout.library/LT_MenuControlTagList

   NAME
    LT_MenuControlTagList -- Manipulate menus, menu/submenu items (V11)

   SYNOPSIS
    LT_MenuControlTagList(Window,Menu,Tags)
                           A0   A1     A2

    VOID LT_MenuControlTagList(struct Window *,struct Menu *,struct TagItem *);

    VOID LT_MenuControlTags(struct Window *,struct Menu *,...);

   FUNCTION
    This routine provides a rather efficient way to set and to clear,
    to enable and to disable a number of menus, menu/submenu items
    all at once.

    In v18 this routine was modified to disconnect a menu strip
    from a window if it is about to change checkmark states. In
    earlier releases or if a single menu is attached to several
    windows it is recommended that you disconnect the menu from
    the windows it is attached to before you call this routine.

    As of v18 this routine is smart enough to handle menu
    mutual exclusion.

   INPUTS
    Window - Pointer to Window this menu is attached to. Starting with
             gtlayout.library v16 this parameter may be NULL.

    Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.

    Tags - Pointer to a list of tagitem values, as found
           in gtlayout.h


    Tags:

    LAMN_ID (ULONG) - Unique ID of menu/menu item/submenu item to
        manipulate.

    LAMN_Checked (BOOL) - Set the checkmark state of the
        menu/submenu item.

    LAMN_Disabled (BOOL) - Set the availability state of the
        menu/menu item/submenu item.

    LAMN_FullMenuNum (UWORD) - Intuition menu number of
        menu/submenu item to manipulate. You would pass the
        result of the FULLMENUNUM() macro here for the
        item in question. (V30)

   RESULT
    none

   EXAMPLE
    The following tagitem list will clear the checkmark and
    disable the menu item associated with ID 5 and set the
    checkmark for the item associated with ID 6:

        LAMN_ID,         5,
          LAMN_Checked,  FALSE,
          LAMN_Disabled, TRUE,
        LAMN_ID,         6,
          LAMN_Checked,  TRUE,
        TAG_DONE

   BUGS
    In library versions up to and including v17.2 this routine
    is broken. It won't do any harm, it just doesn't do what you
    want it to do.

    Up to and including V42.1 the library could fail to find the
    correct menu items corresponding to the LAMN_ID given. This
    has been fixed in V43.1.

    Up to and including V43.1 trying to change the attributes
    of an item with LAMN_ID whose ID number could not be found
    could lead to a crash. This has been fixed in V43.2.

   SEE ALSO
    gtlayout.library/LT_NewMenuTagList

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.


    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
                POPUP_KIND
                TAB_KIND
                MX_KIND
                XBAR_KIND
                YBAR_KIND
                TAPEDECK_KIND
                LEVEL_KIND
                BOOPSI_KIND
                BLANK_KIND (V36)
                FRACTION_KIND (V38)
                IMAGE_KIND (V41)
                TEXTEDIT_KIND (V46)

        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 LAHN_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. (V9)

        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.


        BLANK_KIND (transparent placeholder):

            (requires gtlayout.library V36 or higher)

            No tags are defined for this type of object.


        BOOPSI_KIND:

            (requires gtlayout.library V10 or higher)

            LABO_TagCurrent (Tag) - The Tag ID that represents the
                current object value. For PROPGCLASS this would be
                PGA_Top.

            LABO_TagTextAttr (Tag) - The Tag ID that represents the
                TextAttr value the object expects. For gadgets this
                would be GA_TextAttr.

            LABO_TagDrawInfo (Tag) - The Tag ID that represents the
                DrawInfo value the object expects.

            LABO_TagLink (Tag) - The Tag ID that represents a pointer
                to a different object the object expects. For the
                colorwheel.gadget this would be WHEEL_GradientSlider.

            LABO_TagScreen (Tag) - The Tag ID that represents the
                screen the object expects. For the colorwheel.gadget
                this would be WHEEL_Screen.

            LABO_Link (LONG) - The ID of the object this object should
                be linked to. This will be resolved later when gadgets
                are created.

                    NOTE: Forward references are not resolved, only
                        backward references are allowed. This means that
                        if you wish to link object A to object B,
                        object A must be created before object B
                        is created.

            LABO_ClassInstance (Class *) - This is the first parameter
                you would pass to NewObjectA().

                    NOTE: Only classes derived from gadgetclass and
                      gadgetclass itself may be used.

            LABO_ClassName (STRPTR) - This is the second parameter you would
                pass to NewObject().

                    NOTE: Only classes derived from gadgetclass and
                        gadgetclass itself may be used.

            LABO_ClassLibraryName (STRPTR) - This tag is particularly useful
                for gadget class implementations wrapped into libraries, such as
                colorwheel.gadget. When opened, they make the classes they
                represent publicly available so subsequent calls to
                NewObject(NULL,<Classname>,...) can be made. The
                LABO_ClassLibraryName tag will cause gtlayout.library to open
                the class library before any calls to NewObject() are made.

                    NOTE: Only classes derived from gadgetclass and
                        gadgetclass itself may be used.

                        The LABO_ClassLibraryName tag requires that you
                        specify the class name with the LABO_ClassName. It is
                        not enough to just use the LABO_ClassLibraryName tag.

            LABO_ExactWidth (WORD) - This is the exact width of the object to
                use. This effectively overrides whatever you specified using
                the LA_Chars tag and keeps gtlayout.library from shrinking and
                expanding the object as needed.

            LABO_ExactHeight (WORD) - This is the exact height of the object to
                use. This effectively overrides whatever you specified using
                the LA_Lines tag and keeps gtlayout.library from shrinking and
                expanding the object as needed.

            LABO_RelFontHeight (WORD) - This tag affects the height of the
                object; when specified, it is derived from the user interface
                font height plus the value given with LABO_RelFontHeight.

            LABO_FullWidth (BOOL) - Use this tag if you wish the object to
                cover the entire width of the group it resides within.

            LABO_FullHeight (BOOL) - Use this tag if you wish the object to
                cover the entire height of the group it resides within.

            LABO_ActivateHook (struct Hook *) - Hook to invoke when the
                layout engine decides that this particular object should
                be activated. The hook is called with the following
                parameters:

                Success = ActivateFunc(struct Hook *Hook,LayoutHandle *Handle,
                  D0                                 A0                  A2

                             Object *object)
                                       A1

                The object pointer actually refers to the instance of the
                BOOPSI object created. Return FALSE if your object could not
                be activated, TRUE if it worked. If you return TRUE, no special
                keyboard event will be generated. (V13)

            NOTE: All tags passed to LT_New() for BOOPSI_KIND objects are
                passed through to NewObjectA() later. The library makes
                a copy of the tag item list, so all data valid in the
                scope when LT_New() is called must also be valid later
                when LT_Build() is invoked.

                The gadget label is *NOT* passed through to the object,
                it effectively receives the label a plain gadtools object
                would receive, similar to what happens to FRAME_KIND
                objects and the like.


        BOX_KIND (multiline text display):

            LABX_Chars (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.
               Default: 10

            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 height of this object in
                characters.

            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

            LABX_FirstLine (LONG) - Locale string ID of the first
                text to print inside the box. Works in conjunction
                with LABX_LastLine. (V26)

            LABX_LastLine (LONG) - Locale string ID of the last
                text to print inside the box. Works in conjunction
                with LABX_FirstLine. (V26)

            LABX_LineTable (LONG *) - Pointer to an array of IDs
                to use for building the box contents lines. This requires
                that a locale hook is provided with the layout handle.
                The array is terminated by -1. (V28)

            LABX_Line (STRPTR) - Line to display in the box, may
                contain '\n' line break characters, the layout engine
                will chop the single line into single consecutive lines
                following the '\n' chars. (V31)

            LABX_LineID (LONG) - Locale ID of line text to display in the
                box, may contain '\n' line break characters, the layout
                engine will chop the single line into single consecutive lines
                following the '\n' chars. (V31)

            LABX_TextPen (WORD) - Box text colour to use. (V40)

            LABX_BackPen (WORD) - Box text background colour to use. (V40)

            LABX_Spacing (UWORD) - Request that additional pixels should
                separate lines of text. (V41)
                Default: 0


        BUTTON_KIND:

            LA_Label (STRPTR)
            LA_LabelID (LONG) - These two define the button label, i.e.
                the text that is printed within the button box. Optionally,
                this text may include newline characters ("\n") which will
                cause the button text to be broken into several lines.
                This particular feature requires gtlayout.library v12 or
                higher. Single line label have always been supported.

            LABT_ReturnKey (BOOL) - Let the user operate this
                button by pressing the return key, making it the
                so-called default button, or default choice. The
                button select box will appear slightly bolder than
                normal buttons are.

                    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

            LABT_Lines (STRPTR *) - Use the given string array
                to create a multiline gadget label. Terminate the
                array with a NULL. (V12)

            LABT_FirstLine (LONG) - Locale ID of first label line. (V12)

            LABT_LastLine (LONG) - Locale ID of last label line. (V12)

            LABT_DefaultCorrection (BOOL) - Make the button slightly
                wider and taller so its size matches the default
                button. (V21)

            LABT_Smaller (BOOL) - Make this button a little smaller
                than usual. (V21)


        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. (V9)

                    NOTE: there can be only one single button per
                        window to use this feature.

                Default: FALSE

            LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object
                which will be set to the gadget's current setting.
                If this tag is set, you will hear no events from this
                object any more. (V7)

                    NOTE: Listen to IDCMP_CLOSEWINDOW events
                        which may be generated if the layout
                        engine runs out of memory when rebuilding
                        the user interface.


        FRACTION_KIND:

            (requires gtlayout.library V38 or higher)

            This is a special kind of STRING_KIND which comes with a
            special input filter. It will allow only for floating point
            numbers to be entered, i.e. numbers (`0'-`9') and one
            decimal point (`.' or whatever your current locale uses
            as the decimal point character). What you will receive as
            user input text will be in the following format:

                (0|#[0-9]).(0|#[0-9])

            Or in other words, text like this will be returned:

                0.0
                7.0
                0.9
                146654.0

            NOTE: While this object type did exist in earlier library
                  versions support for it was removed in V33. It was
                  eventually reintroduced with the functionality described
                  above in V38.

            LAFR_IncrementerHook (struct Hook *) - Hook to invoke when the
                incrementer arrows are used. The hook function will receive
                three parameters and has to return a result code:

                    a0 - (struct Hook *)  Pointer to this hook
                    a2 - (STRPTR) Current value of this object
                    a1 - (LONG) Either INCREMENTERMSG_Decrement or
                                INCREMENTERMSG_Increment

                If the hook function modifies the current value it must
                return TRUE, otherwise FALSE must be returned. If you return
                TRUE, then the library will update the object. (V40)

            This object type accepts all the GTST_#? tag items.


        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. (V9)

            LAFR_GenerateEvents (BOOL) - If TRUE, clicking
                inside the FRAME_KIND object will generate
                IDCMP_GADGETUP/IDCMP_GADGETDOWN events. If
                you wish to know where the click occured,
                make a copy of the Window->MouseX/Y entries
                before you call LT_HandleInput()/LT_GetIMsg(). (V28)
                Default: FALSE

            LAFR_ResizeX (BOOL) - Makes this frame resizable
                in the horizontal direction, attaches a sizing
                gadget to the window to open and handles window
                resize operations automatically. (V44)

                    NOTE: there can be only one single object
                        per window to sport this feature. This
                        means that you won't be able to have
                        both a resizable listview and a resizable
                        frame in the same window.

                        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

            LAFR_ResizeY (BOOL) - Makes this frame resizable
                in the vertical direction, attaches a sizing
                gadget to the window to open and handles window
                resize operations automatically. (V44)

                    NOTE: there can be only one single object
                        per window to sport this feature. This
                        means that you won't be able to have
                        both a resizable listview and a resizable
                        frame in the same window.

                        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

        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.

            LAGA_Tenth (BOOL) - Instead of a continuously growing
                bar you will get a set of exactly ten blocks,
                each separated by a hairline. (V19)
                Default: FALSE

               LAGA_NoTicks (BOOL) - If TRUE suppresses drawing the
                   ticks below the gauge box.
                   Default: FALSE


        IMAGE_KIND (display area for Image or BitMap data):

            (requires gtlayout.library V41 or higher)

            LAIM_Image (struct Image *) - Image to draw in this
                place. When the user interface is built, it will
                be drawn using intuition.library/DrawImage().

            LAIM_BitMap (struct BitMap *) - You can supply a
                BitMap instead of an Image which will be drawn
                using either graphics.library/BltBitMapRastPort()
                or graphics.library/BltMaskBitMapRastPort() if
                a mask is provided.

            LAIM_BitMapLeft (UWORD) - Left corner of the image data
                to blit into the window (the second parameter for
                BltBitMapRastPort()).

            LAIM_BitMapTop (UWORD) - Top corner of the image data
                to blit into the window (the third parameter for
                BltBitMapRastPort()).

            LAIM_BitMapWidth (UWORD) - Width of the bitmap area to
                blit into the window.

            LAIM_BitMapHeight (UWORD) - Height of the bitmap area to
                blit into the window.

            LAIM_BitMapMask (PLANEPTR) - Pointer to a bit plane mask
                to blit the image bitmap through. Must follow the
                rules documented for for BltMaskBitMapRastPort().
                The blit operation will use the minterm for
                transparency.


        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

            LAIN_Activate (BOOL) - When the window opens, make this
                gadget the active one. (V21)

                    NOTE: There can be only one gadget of this type
                        per window.

                Default: FALSE


        LEVEL_KIND:

            All tags are supported which SLIDER_KIND supports.
            The gadget level display however, can only be aligned
            to the left border.

            LAVL_Freedom (WORD) - Selects the orientation of the
                slider body; can be either FREEHORIZ or FREEVERT. (V41)

                Default: FREEHORIZ

            LAVL_Ticks (WORD) - Selects if and where to place tick
                marks next to the slider body. Can be one of the
                the following: TICKS_None (no ticks), TICKS_Left
                (place ticks left of the body), TICKS_Above (place
                ticks above the body), TICKS_Both (place ticks on
                both sides of the body). (V41)

                Default: TICKS_None

            LAVL_NumTicks (LONG) - Number of tick marks to draw. (V41)

            LAVL_Lines (LONG) - Height of the slider, if FREEVERT. (V41)


        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 still 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. (V9)

                    NOTE: there can be only one single object
                        per window to sport this feature. This
                        means that you won't be able to have
                        both a resizable listview and a resizable
                        frame in the same window.

                        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. (V9)

                    NOTE: there can be only one single object
                        per window to sport this feature. This
                        means that you won't be able to have
                        both a resizable listview and a resizable
                        frame in the same window.

                        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. (V9)

            LALV_MinLines (WORD) - Minimum height for this
                object, measured in lines. Used in
                conjunction with LALV_ResizeY. (V9)

            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. (V8)

            LALV_FlushLabelLeft (BOOL) - For a gadget label placed
                above the listview align the text to the left edge
                of the view. (V9)

            LALV_TextAttr (struct TextAttr *) - You can specify a
                fixed-width font to be used for the list display.
                The TextAttr (or TTextAttr) you provide must be ready
                to go so the layout code can open the font later.

                To get the current system default font, which is
                guaranteed to be fixed-width, pass ~0 instead of a
                pointer to a TextAttr structure. (V10)

                    NOTE: The font *MUST* be fixed-width or the layout
                        will fail.

                         Choose your font in such a way that it matches
                         in width and height with the other probably
                         proportional-spaced user interface font.

                         If the layout engine decides to step down in
                         font size, all LISTVIEW_KIND objects which were
                         configured to use a special fixed-width font
                         will `forget' about it. This won't matter much
                         as the fonts the engine chooses will always be
                         fixed-width anyway.

            LALV_AutoPageID (LONG) - ID of paged GROUP_KIND object
                which will be set to the gadget's current setting.
                If this tag is set, you will hear no events from this
                object any more. (V23)

                    NOTE: Listen to IDCMP_CLOSEWINDOW events
                        which may be generated if the layout
                        engine runs out of memory when rebuilding
                        the user interface.

            LALV_Selected (LONG) - In this context, this tag is an
                alias for GTLV_Selected. See
                gtlayout.library/LT_SetAttributes for more information
                on how the meaning of this tag differs from this (V34).


        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. (V9)

                    NOTE: there can be only one single button per
                        window to use this feature.

                Default: FALSE

            LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object
                which will be set to the gadget's current setting.
                If this tag is set, you will hear no events from this
                object any more. (V7)

                    NOTE: Listen to IDCMP_CLOSEWINDOW events
                        which may be generated if the layout
                        engine runs out of memory when rebuilding
                        the user interface.


        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

            LAPA_UsePicker (BOOL) - This tag effectively changes the
                gadget type. Instead of a list of colours to pick from
                the user will see a rectangle filled in the selected
                colour with a picker button next to it. This gadget
                will generate IDCMP_IDCMPUPDATE events when the picker
                button is pressed. (V10)


        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

            LAPW_HistoryLines (LONG) - Number of lines to keep as
                a backlog.
                Default: 0

            LAPW_HistoryHook (struct Hook *) - Hook code to call
                when entering a line into the backlog. See gtlayout.h
                for more information.
                Default: NULL

            LAPW_Activate (BOOL) - When the window opens, make this
                gadget the active one. (V21)

                    NOTE: There can be only one gadget of this type
                        per window.

                Default: FALSE

            This object type accepts all the GTST_#? tag items.


        POPUP_KIND:

            (This features requires gtlayout.library v22 or higher
             and Kickstart 3.0 or higher).

            LAPU_FirstLabel (LONG) - Locale string ID of the first
                text to use as a label. Works in conjunction
                with LAPU_LastLabel.

            LAPU_LastLabel (LONG) - Locale string ID of the last
                text to use as a label. Works in conjunction
                with LAPU_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.

            LAPU_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.

            LAPU_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

            LAPU_AutoPageID (LONG) - ID of paged GROUP_KIND object
                which will be set to the gadget's current setting.
                If this tag is set, you will hear no events from this
                object any more.

                    NOTE: Listen to IDCMP_CLOSEWINDOW events
                        which may be generated if the layout
                        engine runs out of memory when rebuilding
                        the user interface.

            LAPU_CentreActive (BOOL) - If TRUE, the popup menu will
                appear with the currently active entry centred below
                the mouse pointer. (V31)

            LAPU_Labels (STRPTR *) - Pointer to NULL-terminated array
                of strings that are the choices offered.


        SCROLLER_KIND:

            LASC_Thin (BOOL) - Make the scroller a bit thinner
                than usual.
                Default: FALSE

            GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP
                event from scroller.
                Default: TRUE

                        NOTE: This is different from what
                         gadtools.library uses.

            GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN
                event from scroller
                Default: TRUE

                        NOTE: This is different from what
                         gadtools.library uses.


        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


        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

            LAST_Activate (BOOL) - When the window opens, make this
                gadget the active one. (V21)

                    NOTE: There can be only one gadget of this type
                        per window.

                Default: FALSE


        TAB_KIND:

            (This features requires gtlayout.library v24 or higher)

            LATB_FirstLabel (LONG) - Locale string ID of the first
                text to use as a label. Works in conjunction
                with LATB_LastLabel.

            LATB_LastLabel (LONG) - Locale string ID of the last
                text to use as a label. Works in conjunction
                with LATB_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.

            LATB_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.

            LATB_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

            LATB_AutoPageID (LONG) - ID of paged GROUP_KIND object
                which will be set to the gadget's current setting.
                If this tag is set, you will hear no events from this
                object any more.

                    NOTE: Listen to IDCMP_CLOSEWINDOW events
                        which may be generated if the layout
                        engine runs out of memory when rebuilding
                        the user interface.

            LATB_FullSize (BOOL) - By default a TAB_KIND object
                covers the entire width of the group it sits in.
                With LATB_FullSize set to true it will cover the
                width of the entire Window.

                Default: FALSE

            LATB_Labels (STRPTR *) - Pointer to NULL-terminated array
                of strings that are the choices offered.


        TAPEDECK_KIND:

            LATD_ButtonType (LONG) - Select the image to display
                in the button, must be one of the following:

                    TDBT_BACKWARD
                        "<<" Symbol

                    TDBT_FORWARD
                        ">>" Symbol

                    TDBT_PREVIOUS
                        "|<" Symbol

                    TDBT_NEXT
                        ">|" Symbol

                    TDBT_STOP
                        Stop symbol (filled square)

                    TDBT_PAUSE
                        "||" pause symbol (broken square)

                    TDBT_RECORD
                        Record symbol (filled circle)

                    TDBT_REWIND
                        "<" symbol

                    TDBT_EJECT
                        Eject symbol (broken upward pointing arrow)

                    TDBT_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

            LATD_Tick (BOOL) - Hear IDCMP_GADGETUP events while the
                buttons is being pressed; the IntuiMessage->Code entry
                will be 0 while the button is being pressed, and
                will be 1 as soon as the button is released. (V12)

                Default: FALSE


        TEXT_KIND:

            LATX_Picker (BOOL) - Attach a `select' button to the
                right hand side of the text display.
                Default: FALSE

            LATX_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 TEXT_KIND object in a paged group
                and update its contents later. You need
                to specify an object width using LA_Chars, otherwise
                the layout engine may make it not wide enough to
                display any text. (V15)

        TEXTEDIT_KIND (multiline string gadget):

            (requires gtlayout.library V46 or higher)

            LATE_String (STRPTR) - Pointer to the string to be
                edited.

            LATE_CursorPosition (ULONG) - Index number of the
                character the cursor should be positioned on.
                For example, in the string "abcd", the index
                number 0 would put the cursor on the "a" and
                the number 3 would put it on the "d".

            LATE_Chars (LONG) - Width of the text editing area
                in characters.

            LATE_Lines (LONG) - Height of the text editing area
                in lines.

            LATE_TextAttr (struct TextAttr *) - You can specify the
                font to be used for the editing area.
                The TextAttr (or TTextAttr) you provide must be ready
                to go so the layout code can open the font later.

                To get the current system default font, which is
                guaranteed to be fixed-width, pass ~0 instead of a
                pointer to a TextAttr structure.

        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. (V7)

            LAGR_IndentX (BOOL) - Add extra horizontal indentation
                for this group. (V10)

            LAGR_IndentY (BOOL) - Add extra vertical indentation
                for this group. (V10)

            LAGR_NoIndent (BOOL) - Inhibit automatic size adjustion
                and centring of this group if it is smaller than
                the neighbouring groups. (V21)

            LAGR_SameWidth (WORD) - During the final layout pass,
                make this group the same width as the group which
                uses the given ID. Not implemented yet. (V25)

            LAGR_SameHeight (WORD) - During the final layout pass,
                make this group the same height as the group which
                uses the given ID. Not implemented yet. (V25)

            LAGR_FrameGroup (UWORD) - Surround this group with a
                frame. Must be one of FRAMETYPE_Label or FRAMETYPE_Tab.
                FRAMETYPE_Label works like "LAGR_Frame,TRUE," while
                FRAMETYPE_Tab is for use with a TAB_KIND object you
                must put directly on top of this group or the group
                will look a little silly. (V38)

                Default: FRAMETYPE_None


        XBAR_KIND (horizontal separator bar):

            LAXB_FullSize (BOOL) - Make this separator bar span
                the entire window width.


        YBAR_KIND (vertical separator bar):

            No tags are defined for this type of object.


   RESULT
    none

   BUGS
    Up to v25 the SCROLLER_KIND object did not support GA_Immediate
    or GA_RelVerify. The space for the variables was there, but the
    code was missing.

    POPUP_KIND objects don't work well in simple refresh windows,
    as refresh events can get lost. Use a smart refresh window
    instead or call gadtools.library/LT_CatchUpRefresh() regularly.

   SEE ALSO
    gadtools.library/CreateGadgetA

gtlayout.library/LT_NewLevelWidth           gtlayout.library/LT_NewLevelWidth

   NAME
    LT_NewLevelWidth -- Determine the maximum width of a SLIDER_KIND
                        level string. (V14)

   SYNOPSIS
    Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
      D0                    A0        A1         A2     D0  D1    A3

                              MaxLen,FullCheck);
                                D3      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.

   NOTES
    This function does exactly what gtlayout.library/LT_LevelWidth
    does, but uses a slightly different register ordering. Namely,
    the MaxLen pointer is passed in D3 instead of A5.

   SEE ALSO
    gtlayout.library/LT_LevelWidth

gtlayout.library/LT_NewMenuTagList         gtlayout.library/LT_NewMenuTagList

   NAME
    LT_NewMenuTagList -- Allocate and layout menu items (V11)

   SYNOPSIS
    Menu = LT_NewMenuTagList(Tags)
     D0                       A0

    struct Menu *LT_NewMenuTagList(struct TagItem *);

    struct Menu *LT_NewMenuTags(...);

   FUNCTION
    Allocates Menus and MenuItems similar to LT_LayoutMenus().

    As of v18 this routine will validate menu mutual exclusion
    information.

   INPUTS
    Tags - Pointer to a list of tagitem values, as found
        in gtlayout.h


    Valid tags include:

    LAMN_Screen (struct Screen *) - Pointer to the Screen
        the menu is to appear upon. This tag is mandatory,
        unless the LAMN_LayoutHandle tag is used.

    LAMN_TextAttr (struct TextAttr *) - Pointer to the
        TextAttr to use for the menu layout. If this tag
        is omitted the Screen->Font will be used.

    LAMN_Error (LONG *) - Pointer to variable to receive
        an error in case of failure.

    LAMN_AmigaGlyph (struct Image *) - Pointer to Image to
        use as the Amiga glyph in menus. Will be ignored if
        NULL.

        NOTE: Ignored by intuition.library v37 and below.

    LAMN_CheckmarkGlyph (struct Image *) - Pointer to Image to
        use as the checkmark glyph in menus. Will be ignored
        if NULL.

    LAMN_LayoutHandle (LayoutHandle *) - Pointer to a valid
        LayoutHandle as created by LT_CreateHandle. This tag
        provides all the information the single tags
        LAMN_Screen..LAMN_CheckmarkGlyph would otherwise
        need to provide.

    LAMN_TitleText (STRPTR) - Name of new menu to create.
        You may precede the name with the keyboard shortcut
        to assign to this menu item as follows:

           A\0Save as...

        This will create a menu item using the shortcut "A"
        and the title "Save as...".

    LAMN_TitleID (LONG) - Locale ID corresponding to the
        name of the new menu to create.
        You may precede the name with the keyboard shortcut
        to assign to this menu item as follows:

           A\0Save as...

        This will create a menu item using the shortcut "A"
        and the title "Save as...".

    LAMN_ItemText (STRPTR) - Name of new menu item to create.
        You may precede the name with the keyboard shortcut
        to assign to this menu item as follows:

           A\0Save as...

        This will create a menu item using the shortcut "A"
        and the title "Save as...".

    LAMN_ItemID (LONG) - Locale ID corresponding to the
        name of the new menu item to create.
        You may precede the name with the keyboard shortcut
        to assign to this menu item as follows:

           A\0Save as...

        This will create a menu item using the shortcut "A"
        and the title "Save as...".

    LAMN_SubText (STRPTR) - Name of new submenu item to create.
        You may precede the name with the keyboard shortcut
        to assign to this menu item as follows:

           A\0Save as...

        This will create a menu item using the shortcut "A"
        and the title "Save as...".

    LAMN_SubID (LONG) - Locale ID corresponding to the
        name of the new submenu item to create.
        You may precede the name with the keyboard shortcut
        to assign to this menu item as follows:

           A\0Save as...

        This will create a menu item using the shortcut "A"
        and the title "Save as...".

    LAMN_KeyText (STRPTR) - Pointer to the string whose first
        character will be used as the keyboard shortcut for
        this menu/submenu item.

    LAMN_KeyID (LONG) - Locale ID corresponding to the string whose
        first character will be used as the keyboard shortcut for
        this menu/submenu item.

    LAMN_CommandText (STRPTR) - Pointer to the string which
        will be used as the keyboard shortcut for this
        menu/submenu item.

    LAMN_CommandID (LONG) - Locale ID corresponding to the string
        which will be used as the keyboard shortcut for
        this menu/submenu item.

    LAMN_MutualExclude (ULONG) - Mutual exclusion information for
        this menu/submenu item.

    LAMN_UserData (APTR) - User data information for this
        menu/menu item/submenu item.

    LAMN_Disabled (BOOL) - Controls whether this
        menu/menu item/submenu item should be disabled.

    LAMN_CheckIt (BOOL) - Controls whether this menu/submenu item
        should be prepared to hold a checkmark.

            NOTE: This does not set the checkmark, use LAMN_Checked
                for this purpose.

    LAMN_Checked (BOOL) - Controls whether this menu/submenu item
        should be marked with a checkmark. This tag implies
        "LAMN_CheckIt,TRUE".

    LAMN_Toggle (BOOL) - Controls whether this menu/submenu item
        should be prepared to hold a checkmark the user is to
        toggle on demand. This tag implies "LAMN_CheckIt,TRUE".

            NOTE: this does not set the checkmark, use LAMN_Checked
                for this purpose.

    LAMN_Code (UWORD) - Raw key code to associate with this
        menu/submenu item. To find out if a rawkey event
        corresponds to this menu item use LT_FindMenuCommand.

    LAMN_Qualifier (ULONG) - Key qualifier to associate
        with this menu/submenu item.

            NOTE: the comparison does not distinguish between
                the left and right shift/caps/alt qualifier keys.

    LAMN_ID (ULONG) - Unique ID to associate with this
        menu/menu item/submenu item. You can use this
        later to look up data using LT_GetMenuItem, etc.

    LAMN_ExtraSpace (UWORD) - Number of pixels to put between
        neighbouring menu titles. (V18)
        Default: 0 pixels.

   RESULT
    Menu - Pointer to Menu structure, ready to pass to
           SetMenuStrip(), NULL on failure.

   EXAMPLE
    The following tagitem list:

        LAMN_TitleText,     "Project"
         LAMN_ItemText,     "New",
          LAMN_KeyText,     "N",
         LAMN_ItemText,     "Open...",
          LAMN_KeyText,     "O",
         LAMN_ItemText,     NM_BARLABEL,
         LAMN_ItemText,     "Save",
          LAMN_KeyText,     "S",
         LAMN_ItemText,     "A\0Save As...",
         LAMN_ItemText,     NM_BARLABEL,
         LAMN_ItemText,     "Print...",
          LAMN_KeyText,     "P",
         LAMN_ItemText,     NM_BARLABEL,
         LAMN_ItemText,     "Help...",
          LAMN_CommandText, "[Help]",
         LAMN_ItemText,     NM_BARLABEL,
         LAMN_ItemText,     "Quit...",
          LAMN_KeyText,     "Q",
        TAG_DONE

    Will create the following menu:

    +-------+
    |Project|
    +-------+------+
    |New         aN|
    |Open...     aO|
    |~~~~~~~~~~~~~~|
    |Save        aS|
    |Save As...  aA|
    |~~~~~~~~~~~~~~|
    |Print...    aP|
    |~~~~~~~~~~~~~~|
    |Help... [Help]|
    |~~~~~~~~~~~~~~|
    |Quit...     aQ|
    +--------------+

   NOTES
    You may freely add, remove, spindle & mutilate the contents of the
    menu strip created, just don't trash or disconnect the base menu
    entry this routine creates as all menu memory tracking data is
    connected to it.

   SEE ALSO
    gtlayout.library/LT_DisposeMenu
    gtlayout.library/LT_FindCommandItem
    gtlayout.library/LT_GetMenuItem
    gtlayout.library/LT_LayoutMenuA
    gtlayout.library/LT_MenuControlTagList
    gtlayout.library/LT_NewMenuTemplate
    intuition.library/SetMenuStrip

gtlayout.library/LT_NewMenuTemplate       gtlayout.library/LT_NewMenuTemplate

   NAME
    LT_NewMenuTemplate -- Allocate and layout menu items (V11)

   SYNOPSIS
    Menu = LT_NewMenuTemplate(Screen,TextAttr,AmigaGlyph,CheckmarkGlyph,
     D0                         A0      A1        A2           A3

                              Error,MenuTemplate);
                                D0      D1

    struct Menu *LT_NewMenuTemplate(struct Screen *,struct TextAttr *,
                                    struct Image *,struct Image *,
                                    LONG *,struct NewMenu *);

   FUNCTION
    Allocates Menus and MenuItems similar to LT_LayoutMenus().

    As of v18 this routine will validate menu mutual exclusion
    information.

   INPUTS
    Screen - Pointer to the screen the menu will appear on. This
        parameter is required and must not be omitted.

    TextAttr - Pointer to the TextAttr that should be used to
        layout the menus. If this parameter is omitted,
        Screen->Font will be used instead.

    AmigaGlyph - Pointer to the Image to use as the Amiga glyph.
        This parameter may be omitted.

            NOTE: Ignored by intuition.library v37 and below.

    CheckmarkGlyph - Pointer to the Image to use as the checkmark
        glyph. This parameter may be omitted.

    Error - Pointer to receive error code in case the menu
        creation or layout process fails. This parameter
        may be omitted.

    MenuTemplate - Pointer to a series of NewMenu structures,
        just as you would pass to
        gtlayout.library/LT_LayoutMenuA.

   RESULT
    Menu - Pointer to Menu structure, ready to pass to
        SetMenuStrip(), NULL on failure.

   NOTES
    The menu created by this function cannot be used with the
    routines LT_MenuControlTagList, LT_FindMenuCommand and
    LT_GetMenuItem.

    You may freely add, remove, spindle & mutilate the contents of the
    menu strip created, just don't trash or disconnect the base menu
    entry this routine creates as all menu memory tracking data is
    connected with it.

   SEE ALSO
    gtlayout.library/LT_DisposeMenu
    gtlayout.library/LT_LayoutMenuA
    gtlayout.library/LT_NewMenuTagList
    intuition.library/SetMenuStrip

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
    Success = LT_PressButton(Handle,ID);
       D0                       A0  D0

    BOOL LT_PressButton(LayoutHandle *,LONG);

        NOTE: The return value did not exist until V39!

   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.

    As of V39 and beyond this function will indicate whether the button
    could be highlighted or not.

   INPUTS
    Handle - Pointer to LayoutHandle structure

    ID - ID of button object to highlight

   RESULT
    Success (V39) - TRUE if button could be highlighted, FALSE otherwise.

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.


    Valid tags include:

    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.

   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.

gtlayout.library/LT_Redraw                         gtlayout.library/LT_Redraw

   NAME
    LT_Redraw -- Redraw a single object (V47).

   SYNOPSIS
    LT_Redraw(handle,id)
               A0    D0

    VOID LT_Redraw(LayoutHandle * handle,LONG id);

   FUNCTION
    This function is for redrawing a single object, as contained in
    a window. This is not always necessary as the library will handle
    display updates automatically. Please note that if this routine cannot
    find the object you specified, it will resort to redraw the contents
    of the entire window and no just a single element.

   INPUTS
    handle -- Pointer to a LayoutHandle structure.
    id -- Numeric identifier of the object to redraw.

   RESULT
    none

   SEE ALSO
    intuition.library/BeginRefresh
    intuition.library/EndRefresh
    gtlayout.library/LT_EndRefresh

gtlayout.library/LT_Refresh                       gtlayout.library/LT_Refresh

   NAME
    LT_Refresh -- Redraws the entire window contents.

   SYNOPSIS
    LT_Refresh(Handle)
                 A0

    VOID LT_Refresh(LayoutHandle *);

   FUNCTION
    Redraws the contents of the window, this includes both gadgets
    and imagery.

   INPUTS
    Handle - Pointer to a LayoutHandle structure.

   RESULT
    none

   SEE ALSO
       gadtools.library/GT_RefreshWindow
       intuition.library/RefreshGList

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.

   RESULT
    none

   NOTES
    Only pass IntuiMessages you received via LT_GetIMsg,
    or things will get tough.

   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.


    All gadtools.library tags are allowed, but not all are supported.
    In addition to these tags a few additional tag values are
    supported:

    LAHN_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.

    LAHN_UserData (APTR) - Store user specific data in the
        LayoutHandle->UserData entry. (V9)

    LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
        events. (V13)
        Default: TRUE

    LAHN_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.

    LAHN_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 "LAHN_ExitFlush,FALSE". (V9)
        Default: TRUE

    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.
            As of v26 the LABX_Index tag may be omitted, the library
            will then assume the line index will be 0.

        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
            within the group.

                NOTE: requires that this group was created
                    with the LAGR_ActivePage attribute set.

    INTEGER_KIND:

        LAIN_Min (LONG) - Minimum allowed value for this
            object.

        LAIN_Max (LONG) - Maximum allowed value for this
            object.

    LISTVIEW_KIND:

        LALV_Selected (LONG) - Combines GTLV_Selected and
            GTLV_Top (for Kickstart V37) or GTLV_MakeVisible
            (for Kickstart V39 and greater). This means, the
            list display will be changed in order to show
            the item to be selected. (V34)

    LEVEL_KIND:

        LAVL_NumTicks (WORD) - Number of tick marks to draw
           next to the slider body.

    PASSWORD_KIND:

        LAPW_String (STRPTR) - Secret text to use

    POPUP_KIND

        LAPU_Labels (STRPTR *) - To block access to the popup
            menu, for example before you free the current list
            of labels, you can pass ~0 as the list parameter. (V25)

    STRING_KIND:

        LAST_CursorPosition (LONG) - Repositions the cursor,
            pass -1 to move it to the end of the string. (V7)

    TAPEDECK_KIND:

        LATD_Pressed (BOOL) - TRUE to make this button shown
            as pressed, FALSE to show it in depressed state.

    BOOPSI_KIND:

        All tags are passed straight through to SetGadgetAttrs(..).

    TEXTEDIT_KIND:

        LATE_String (STRPTR) - The string to put into the editing
            area.

        LATE_CursorPosition (LONG) - Index number of the character
            to put the cursor on. Pass -1 to put it to the end
            of the string.

    All objects:

        LA_LabelText (STRPTR) - New gadget label text to use.

        LA_LabelID (LONG) - Locale text ID to use for this object.

   RESULT
    none

   SEE ALSO
    gadtools.library/GT_SetGadgetAttrsA()
    intuition.library/SetGadgetAttrsA

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.

   RESULT
    none

   NOTES
    The arguments are passed in A0 and A1, this is *not* a
    typo.

   BUGS
    In revisions earlier than v21 this routine consistently
    failed to reliably unzip a window in zoomed state. This
    could cause the calling application to wait for about
    five seconds before continuing execution.

   SEE ALSO
    intuition.library/MoveScreen
    intuition.library/ScreenPosition
    intuition.library/ZipWindow

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; passing NULL is harmless.

   RESULT
    none

   SEE ALSO
    gtlayout.library/LT_LockWindow

gtlayout.library/LT_UpdateStrings           gtlayout.library/LT_UpdateStrings

   NAME
    LT_UpdateStrings -- Make sure all visible string buffer contents
                        get written into storage (v9).

   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