home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / jËzyki_programowania / amigae / arismodules / gtlayout / gtlayout.doc next >
Text File  |  1977-12-31  |  130KB  |  3,582 lines
  1. TABLE OF CONTENTS
  2.  
  3. gtlayout.library/--version--
  4. gtlayout.library/--background--
  5. gtlayout.library/LT_Activate
  6. gtlayout.library/LT_BeginRefresh
  7. gtlayout.library/LT_BuildA
  8. gtlayout.library/LT_CreateHandleTagList
  9. gtlayout.library/LT_DeleteHandle
  10. gtlayout.library/LT_DeleteWindowLock
  11. gtlayout.library/LT_DisposeMenu
  12. gtlayout.library/LT_EndGroup
  13. gtlayout.library/LT_EndRefresh
  14. gtlayout.library/LT_Exit
  15. gtlayout.library/LT_FindMenuCommand
  16. gtlayout.library/LT_Fixed2String
  17. gtlayout.library/LT_FixedMult
  18. gtlayout.library/LT_GetAttributesA
  19. gtlayout.library/LT_GetCode
  20. gtlayout.library/LT_GetIMsg
  21. gtlayout.library/LT_GetMenuItem
  22. gtlayout.library/LT_HandleInput
  23. gtlayout.library/LT_Init
  24. gtlayout.library/LT_LabelChars
  25. gtlayout.library/LT_LabelWidth
  26. gtlayout.library/LT_LayoutMenusA
  27. gtlayout.library/LT_LevelWidth
  28. gtlayout.library/LT_LockWindow
  29. gtlayout.library/LT_MenuControlTagList
  30. gtlayout.library/LT_NewA
  31. gtlayout.library/LT_NewLevelWidth
  32. gtlayout.library/LT_NewMenuTemplate
  33. gtlayout.library/LT_NewMenuTagList
  34. gtlayout.library/LT_PressButton
  35. gtlayout.library/LT_RebuildTagList
  36. gtlayout.library/LT_ReplyIMsg
  37. gtlayout.library/LT_SetAttributesA
  38. gtlayout.library/LT_ShowWindow
  39. gtlayout.library/LT_String2Fixed
  40. gtlayout.library/LT_UnlockWindow
  41. gtlayout.library/LT_UpdateStrings
  42. gtlayout.library/--version--                       gtlayout.library/--version--
  43.  
  44. This document describes gtlayout.library v5.12 or higher. Do not assume that
  45. previous library releases support the same features.
  46. gtlayout.library/--background--                 gtlayout.library/--background--
  47.  
  48.     1. General information
  49.  
  50.     1.1 Purpose
  51.  
  52.     The GUI code included in this archive helps to create user interfaces
  53.     using gadtools.library with a minimum of effort. The code
  54.     automatically takes care of the font to be used, making the user
  55.     interface font independent. Localizing support is built right into
  56.     the code, just install a callback hook and pass numeric IDs for the
  57.     gadget labels: the code will invoke your hook in order to get the
  58.     text required. Keystroke activation of gadgets is also taken care
  59.     of, in fact the code will -- unless told not to do so -- assign keyboard
  60.     shortcuts to the gadgets created all on its own. Every effort has been
  61.     made to make the code reentrant, so it can be put into a shared library.
  62.     If a user interface does not fit onto a screen provisions are made to
  63.     choose a smaller font and to rescale the window contents until they fit.
  64.     Last but not least the user interface code offers transparent extensions
  65.     to the standard gadtools.library objects, such as LISTVIEW_KIND objects
  66.     which respond to double-clicks or STRING_KIND objects which can be used
  67.     to enter password text as they will not display the characters entered.
  68.  
  69.  
  70.     1.2 Distribution
  71.  
  72.     The code is *free*, you don't need to pay any money to use it, nor
  73.     do you need to quote my name in the documentation, the program or
  74.     anywhere else. You are allowed to make changes to the code, but if
  75.     you stumble across any bugs or even know how to fix them, please
  76.     let me know. It does not matter whether you intend to sell a program
  77.     to use the code, use the code in shareware, gift-ware, freeware or
  78.     etc.-ware programs: the code still remains royalty-free.
  79.  
  80.  
  81.     1.3 Caveats
  82.  
  83.     The code is pretty large, about 40K-60K bytes in size. Not all
  84.     gadtools.library type objects are supported, notably
  85.     GENERIC_KIND objects. The code is not as flexible as
  86.     gadtools.library, so certain things which are easily done using
  87.     gadtools.library may be pretty difficult or even impossible.
  88.     The code is written entirely in `C' and requires SAS/C to
  89.     compile. Some parts of the code are highly recursive; I haven't
  90.     measured how many stack they might require in certain cases,
  91.     but I recommend that you don't use the grouping feature too
  92.     much. The data structures required to create and maintain the
  93.     user interface are huge, a single window might require more
  94.     than 4K-6K of memory. Proportional font support only works
  95.     well starting with Kickstart v39 and up, v2.04 will probably
  96.     not look quite that pretty.
  97.  
  98.  
  99.     2. Programming
  100.  
  101.     2.1 Client libraries required
  102.  
  103.     You need to have SysBase and GadToolsBase initialized in order to make
  104.     use of the code, i.e. your code has to do
  105.     WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes
  106.     use of the memory pools introduced in exec.library v39, but calls the
  107.     equivalent routines in amiga.lib. Note: as of this writing the pools
  108.     code in amiga.lib v40.14 is broken, so you need to link with Mike
  109.     Sinz' fixed pools.lib.
  110.  
  111.  
  112.     2.2 Invocation procedure
  113.  
  114.     The typical invocation procedure looks roughly like this:
  115.  
  116.        LT_Init();
  117.        :
  118.        :
  119.           LT_CreateHandleTags();
  120.              LT_New();
  121.              :
  122.              :
  123.              LT_New();
  124.                 LT_Build();
  125.                    LT_HandleInput();
  126.           LT_DeleteHandle();
  127.        :
  128.        :
  129.        LT_Exit();
  130.  
  131.     You need to call LT_Init() only once in your program, it will initialize
  132.     the libraries and global data structures required by the user interface
  133.     code. When you are finished with the user interface and your program is
  134.     about to exit you need to call LT_Exit() or memory will get lost.
  135.     Note that LT_Init() is not protected against multiple invocations. If
  136.     called repeatedly memory will get lost which can never be reclaimed.
  137.     However, LT_Exit() is protected against multiple invocations, you can
  138.     also call it before ever giving LT_Init() a call, but I doubt this
  139.     would make much sense. If you are using the shared gtlayout.library
  140.     no call to LT_Init()/LT_Exit() is necessary as these calls are already
  141.     wrapped into the library opening code.
  142.        Before you can actually start building a window layout a call to
  143.     LT_CreateHandleTags() needs to be made. You need to pass in a pointer
  144.     to the Screen your user interface window is to be opened on and,
  145.     optionally, a few tags to control the look and performance of the
  146.     interface. *Never* close the screen in question before calling
  147.     LT_DeleteHandle() or nasty things will happen. For public screens
  148.     the code will try to lock the screen in question. With the handle
  149.     LT_CreateHandleTags() returned you can call LT_New() to build the
  150.     user interface. When finished a call to LT_Build() will finally
  151.     open a window and place the gadgets inside. A pointer to the
  152.     Window created will be returned, ready to be used for the
  153.     WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg()
  154.     loop. When finished, a call to LT_DeleteHandle() will close the
  155.     window and release all the memory associated with it. The design
  156.     of the interface code is similar to the corresponding calls in
  157.     gadtools.library, i.e. you don't need to worry about LT_New()
  158.     failing to allocate memory for the objects required. When it comes
  159.     to LT_Build() the code will know about any trouble which would
  160.     show up during previous invocations of LT_New(). In essence,
  161.     if LT_Build() returns NULL something is wrong.
  162.  
  163.  
  164.     2.3 Hierarchic grouping
  165.  
  166.     The basic building block of the user interface is a group, either
  167.     a horizontal or a vertical group. Adding gadgets or other objects
  168.     to a horizontal group will place them side by side from left to
  169.     right. A vertical group causes objects to be place from top to
  170.     bottom in one straight line. Groups help to arrange objects
  171.     neatly stacked, centered and properly aligned with other
  172.     members of the group.
  173.  
  174.     MUCHO IMPORTANTE: there is a bug lurking in the code which I never
  175.     had the luck to find and fix. One would expect to create
  176.     user interface structures like this:
  177.  
  178.        <group start>
  179.           <button>
  180.           <list>
  181.           <group start>
  182.              <slider>
  183.              <text>
  184.           <group end>
  185.           <button>
  186.        <group end>
  187.  
  188.     However, it is in fact not possible to mix gadgets and groups.
  189.     Thus, the user interface structure would have to look like this:
  190.  
  191.        <group start>
  192.           <group start>
  193.              <button>
  194.              <list>
  195.           <group end>
  196.           <group start>
  197.              <slider>
  198.              <text>
  199.           <group end>
  200.           <group start>
  201.              <button>
  202.           <group end>
  203.        <group end>
  204.  
  205.     Or in other words: groups only mix with other groups.
  206.  
  207.     You build groups using three different object types. In this
  208.     context `object type' refers to a specific numeric value the
  209.     LT_New() routine knows which will cause it to add another leaf
  210.     to the user interface structure tree. Here is an example:
  211.  
  212.        struct LayoutHandle *Handle;
  213.  
  214.        if(Handle = LT_CreateHandleTags(NULL,
  215.           LH_AutoActivate,FALSE,
  216.        TAG_DONE))
  217.        {
  218.           struct Window *Window;
  219.  
  220.           LT_New(Handle,
  221.              LA_Type,      VERTICAL_KIND,  /* A vertical group. */
  222.              LA_LabelText, "Main group",   /* Group title text. */
  223.           TAG_DONE);
  224.           {
  225.              LT_New(Handle,
  226.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  227.                 LA_LabelText, "A button",
  228.                 LA_ID,        11,
  229.              TAG_DONE);
  230.  
  231.              LT_New(Handle,
  232.                 LA_Type,      XBAR_KIND,   /* A separator bar. */
  233.              TAG_DONE);
  234.  
  235.              LT_New(Handle,
  236.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  237.                 LA_LabelText, "Another button",
  238.                 LA_ID,        22,
  239.              TAG_DONE);
  240.  
  241.              LT_New(Handle,
  242.                 LA_Type,      END_KIND,    /* This ends the current group. */
  243.              TAG_DONE);
  244.           }
  245.  
  246.           if(Window = LT_Build(Handle,
  247.             LAWN_Title,     "Window title",
  248.             LAWN_IDCMP,     IDCMP_CLOSEWINDOW,
  249.             WA_CloseGadget, TRUE,
  250.           TAG_DONE))
  251.           {
  252.               struct IntuiMessage *Message;
  253.               ULONG                MsgQualifier,
  254.                                    MsgClass;
  255.               UWORD                MsgCode;
  256.               struct Gadget       *MsgGadget;
  257.               BOOL                 Done = FALSE;
  258.  
  259.               do
  260.               {
  261.                   WaitPort(Window -> UserPort);
  262.  
  263.                   while(Message = GT_GetIMsg(Window -> UserPort))
  264.                   {
  265.                      MsgClass     = Message -> Class;
  266.                      MsgCode      = Message -> Code;
  267.                      MsgQualifier = Message -> Qualifier;
  268.                      MsgGadget    = Message -> IAddress;
  269.  
  270.                      GT_ReplyIMsg(Message);
  271.  
  272.                      LT_HandleInput(Handle,MsgQualifier,&MsgClass,&MsgCode,&MsgGadget);
  273.  
  274.                      switch(MsgClass)
  275.                      {
  276.                         case IDCMP_CLOSEWINDOW:
  277.  
  278.                             Done = TRUE;
  279.                             break;
  280.  
  281.                         case IDCMP_GADGETUP:
  282.  
  283.                             switch(MsgGadget -> GadgetID)
  284.                             {
  285.                                 case 11: printf("First gadget\n");
  286.                                          break;
  287.  
  288.                                 case 22: printf("Second gadget\n");
  289.                                          break;
  290.                             }
  291.  
  292.                             break;
  293.                      }
  294.                   }
  295.               }
  296.               while(!Done);
  297.           }
  298.  
  299.           LT_DeleteHandle(Handle);
  300.        }
  301.  
  302.     The example creates one single group, places a few objects inside,
  303.     calls the layout routine, handles the input and finally cleans
  304.     things up again. This example also shows that you *need* at
  305.     least one group in your tree (to form the root) in order to get
  306.     things to work.
  307.        The input loop requires you to call LT_HandleInput() in order
  308.     to get the user interface code to filter out certain events and
  309.     to update internal information. The data passed in must have
  310.     been processed via the gadtools.library routines. You *must not*
  311.     call LT_HandleInput() before GT_ReplyIMsg() is called since the
  312.     routine may call intuition.library and gadtools.library routines
  313.     which in turn might lead to a system lock-up if the message
  314.     has not been processed yet. The first thing to do after LT_HandleInput()
  315.     has done whatever was necessary to the data you passed in is
  316.     examine the MsgClass variable. The user interface code will
  317.     `fake' certain message events using the variables passed in,
  318.     *do not* use any other data gathered from the original
  319.     IntuiMessage. The MsgClass may include event types you did
  320.     not ask for, i.e. the IDCMP flags of the window opened
  321.     will be set according to the objects you added to the window.
  322.     Also, the IDCMP_IDCMPUPDATE message class will show up for
  323.     certain objects. More on this later in this document.
  324.  
  325.  
  326.     2.4 Setting and getting object attributes
  327.  
  328.     The mechanism to update and query object attributes does not
  329.     exactly match the familiar gadtools.library interface. In
  330.     fact, the routine to change gadget attributes will forward
  331.     the tagitem list passed in to gadtools.library/GT_SetGadgetAttrs().
  332.     On the other hand the routine to query object attributes does
  333.     not work like gadtools.library/GT_GetGadgetAttrs(). The
  334.     user interface code assumes that all objects it can handle and
  335.     create posess certain attributes unique to the type of the
  336.     object in question. For example, the unique attribute of a
  337.     STRING_KIND object would be a pointer to the string it
  338.     `contains'. The unique attribute of a SLIDER_KIND object is
  339.     the current slider position. The LT_GetAttributes() routine
  340.     will return this attribute, but also accept a tagitem list
  341.     to fill in for certain special tag values.
  342.  
  343.  
  344.     2.5 Extra data
  345.  
  346.     Once a LayoutHandle has been created the interface code will
  347.     provide you with a number of information concerning the screen
  348.     the handle has been attached to. This information includes
  349.     the DrawInfo structure of the screen, the VisualInfo data
  350.     and the Screen address. This information is read-only.
  351.  
  352.  
  353.     2.6 Menus
  354.  
  355.     With a LayoutHandle available a routine called LT_LayoutMenuTags()
  356.     will create a standard Intuition menu structure via gadtools.library
  357.     which can be passed to LT_Build(). Note that this
  358.     routine does not modify any data passed in, it does neither
  359.     attach the menu created to the LayoutHandle passed in,
  360.     nor does it change the NewMenu table.
  361.  
  362.  
  363.     2.7 Localization
  364.  
  365.     All object and menu creation routines support localization via
  366.     a Hook callback interface, i.e. you can pass a pointer to an
  367.     initialized Hook structure to LT_CreateHandleTags() which will
  368.     later be used to supply label and list text for objects
  369.     created. The Hook callback routine is called in the following
  370.     fashion:
  371.  
  372.        String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,LONG ID)
  373.          D0                            A0                         A2        A1
  374.  
  375.     Or in other words: a locale string ID is passed in, the routine is supposed
  376.     to look up the string to match this ID and to return it.
  377.  
  378.  
  379.     2.8 Object types to generate IDCMP_IDCMPUPDATE events
  380.  
  381.     Certain objects convey extra information which is merged into the `fake'
  382.     input stream passed to the client calling LT_HandleInput(). These objects
  383.     are:
  384.  
  385.        STRING_KIND
  386.        TEXT_KIND
  387.        PALETTE_KIND
  388.  
  389.           The user pressed the `select' button which belongs
  390.           to this gadget. The MsgGadget pointer indicates the
  391.           STRING_KIND/TEXT_KIND/PALETTE_KIND object the `select'
  392.           button belongs to.
  393.  
  394.        LISTVIEW_KIND
  395.  
  396.           The user double-clicked on an entry. The entry number
  397.           is returned in the MsgCode variable. The MsgGadget
  398.           pointer indicates the LISTVIEW_KIND object the user
  399.           has clicked on.
  400.  
  401.  
  402.     2.9 Keystroke activation
  403.  
  404.     Unless forbidden via the the LA_NoKey tag item the user interface
  405.     code will pick the keyboard shortcuts for all gadgets on its own.
  406.     The currently active global console keymap will be checked at the
  407.     time when LT_Init() is called in order to make sure subsequent
  408.     calls to LT_Build() will use only keys the user can press on
  409.     the keyboard. Double-dead keys are also excluded from the
  410.     table created. This avoids problems with gadget labels such as
  411.     "éééé" which would require the user to hit two keys in a row to
  412.     activate the gadget.
  413.        If the window created happens to feature a close gadget
  414.     pressing the `Esc' key will cause the client to receive
  415.     an IDCMP_CLOSEWINDOW event.
  416.        A single LISTVIEW_KIND object may receive special treatment
  417.     if the LALV_CursorKey tag is used: the user will be able to
  418.     operate the listview using the cursor keys. Note: this
  419.     will also keep the user interface code from choosing a
  420.     special keystroke from the gadget label.
  421.        The user will be able to operate a single BUTTON_KIND
  422.     object using the return key if the LABT_ReturnKey tag is
  423.     used. A recessed frame will be drawn around the button hit
  424.     box to indicate its special status.
  425.        Pressing the Tab key can be bound to operate a cycle or
  426.     mx kind object.
  427.  
  428.     3. Credits
  429.  
  430.     The original design is based upon the user interface layout code used by
  431.     `term' 3.1. I put the first version of the layout routines together back
  432.     in Summer 1993 when I wanted to write the follow-up to `term' v3.4.
  433.  
  434.     Martin Taillefer rewrote large parts of the code, added new routines and
  435.     generally improved the performance of the layout process.
  436.  
  437.     Kai Iske, Christoph Feck, Stefan Becker and Michael Barsoom helped to
  438.     iron out the remaining bugs and piled up bug reports and
  439.     enhancement requests.
  440. gtlayout.library/LT_Activate                      gtlayout.library/LT_Activate
  441.  
  442.    NAME
  443.  
  444.         LT_Activate -- Activate a string type gadget.
  445.  
  446.    SYNOPSIS
  447.  
  448.         LT_Activate(Handle,ID);
  449.                       A0   D0
  450.  
  451.         VOID LT_Activate(LayoutHandle *,LONG);
  452.  
  453.    FUNCTION
  454.  
  455.         The equivalent to intuition.library/ActivateGadget().
  456.  
  457.    INPUTS
  458.  
  459.         Handle - Pointer to LayoutHandle structure.
  460.  
  461.         ID - ID of Gadget to activate.
  462.  
  463.    RESULT
  464.  
  465.         none
  466.    SEE ALSO
  467.  
  468.         intuition.library/ActivateGadget
  469. gtlayout.library/LT_BeginRefresh              gtlayout.library/LT_BeginRefresh
  470.  
  471.    NAME
  472.  
  473.         LT_BeginRefresh -- Optimized window refreshing
  474.  
  475.    SYNOPSIS
  476.  
  477.         LT_BeginRefresh(Handle)
  478.                           A0
  479.  
  480.         VOID LT_BeginRefresh(LayoutHandle *);
  481.  
  482.    FUNCTION
  483.  
  484.         If you wish to handle window refreshing all on your own, you
  485.         might want to use the LT_BeginRefresh...LT_EndRefresh pair
  486.         in your program. By default the user interface layout engine
  487.         will automatically intercept IDCMP_REFRESHWINDOW events and
  488.         react to them accordingly.
  489.  
  490.    INPUTS
  491.  
  492.         Handle - Pointer to a LayoutHandle structure.
  493.  
  494.    RESULT
  495.  
  496.         none.
  497.  
  498.    SEE ALSO
  499.  
  500.         intuition.library/BeginRefresh
  501.         intuition.library/EndRefresh
  502.         gtlayout.library/LT_EndRefresh
  503. gtlayout.library/LT_BuildA                          gtlayout.library/LT_BuildA
  504.  
  505.    NAME
  506.  
  507.         LT_BuildA -- turn the user interface specs into a window
  508.                      and gadgets.
  509.  
  510.    SYNOPSIS
  511.  
  512.         Window = LT_BuildA(Handle,Tags);
  513.           D0                 A0    A1
  514.  
  515.         struct Window *LT_BuildA(LayoutHandle *,struct TagItem *);
  516.  
  517.         Window = LT_Build(Handle,...);
  518.  
  519.         struct Window *LT_Build(LayoutHandle *,...);
  520.  
  521.    FUNCTION
  522.  
  523.         This is the big one. After building up a user interface specification
  524.         using LT_NewA() a call to LT_BuildA() will finally lay out the single
  525.         user interface elements, open a window and put the gadgets, etc.
  526.         inside.
  527.  
  528.         The code tries to fit all the gadgets into the window, but if it
  529.         runs out of space it will fall back to a different font and
  530.         rescale the user interface objects to match it. It will first
  531.         fall back onto the system default font. If unsuccessful it will
  532.         as a last resort try to use topaz.font/8.
  533.  
  534.         To make it easier to distinguish between different handles that
  535.         share the same Window->UserPort, the Window->UserData pointer
  536.         will point to the LayoutHandle that created it (V13).
  537.  
  538.         NOTE: Earlier library releases did not support this feature,
  539.               so be prepared to deal with Window->UserData == NULL.
  540.  
  541.    INPUTS
  542.  
  543.         Handle - Pointer to a LayoutHandle structure.
  544.  
  545.         Tags - Pointer to TagItem list controlling window
  546.                and layout attributes.
  547.  
  548.    TAGS
  549.  
  550.         All the tag values given are passed straight away to OpenWindowTags(),
  551.         see intuition.doc for more information.
  552.  
  553.         In addition to this a number of private tag values are supported:
  554.  
  555.         LAWN_Menu (struct Menu *) - The menu to attach to the window, the
  556.             IDCMP flags will be updated to include IDCMP_MENUPICK if this
  557.             tag is used.
  558.  
  559.         LAWN_MenuTemplate (struct NewMenu *) - A list of filled-in
  560.             NewMenu structures which will get passed straight through
  561.             to LT_NewMenuTemplate(). If a menu could be created, it will
  562.             be attached to the window. LT_DeleteHandle() will then later
  563.             automatically dispose of the menu. Please note that the window
  564.             may fail to open due to the menu layout going wrong. Separate
  565.             calls to LT_NewMenuTemplate() and LT_Build() may be a better
  566.             approach since it is easier to find out which process went
  567.             wrong. You will find a pointer to the menu attached to the
  568.             LayoutHandle in LayoutHandle->Menu. Please note that this
  569.             entry only exists in LayoutHandles created by gtlayout.library
  570.             v13 or higher.
  571.  
  572.             NOTE: This tag effectively overrides LAWN_Menu.
  573.  
  574.             (requires gtlayout.library v13 or higher)
  575.  
  576.         LAWN_MenuTags (struct TagItem *) - A list of TagItems which
  577.             will get passed straight through to LT_NewMenuTagList().
  578.             Even if you don't ask for it, LT_Build() will pass
  579.             "LAMN_Handle,<Handle>" in for you, so any additional tags
  580.             specifying screen, fonts, etc. will be overridden. If a menu
  581.             could be created, it will be attached to the window.
  582.             LT_DeleteHandle() will then later automatically dispose of the
  583.             menu. Please note that the window may fail to open due to the
  584.             menu layout going wrong. Separate calls to LT_NewMenuTagList()
  585.             and LT_Build() may be a better approach since it is easier to
  586.             find out which process went wrong. You will find a pointer to the
  587.             menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
  588.             that this entry only exists in LayoutHandles created by
  589.             gtlayout.library v13 or higher.
  590.  
  591.             NOTE: This tag effectively overrides LAWN_Menu and has
  592.                   precedence over LAWN_MenuTemplate.
  593.  
  594.             (requires gtlayout.library v13 or higher)
  595.  
  596.         LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the
  597.             window user port. The MsgPort will be attached using the
  598.             common ModifyIDCMP() method, closing the window will
  599.             first remove and reply all pending messages at this port.
  600.  
  601.         LAWN_Left (LONG) - The left edge position the window is to use.
  602.             This effectively overrides any horizontal alignment flags.
  603.             NOTE: the code may choose to ignore this value if it finds
  604.                   that the window will not fit onto the screen unless
  605.                   the left edge position is changed.
  606.  
  607.         LAWN_Top (LONG) - The top edge position the window is to use.
  608.             This effectively overrides any vertical alignment flags.
  609.             NOTE: the code may choose to ignore this value if it finds
  610.                   that the window will not fit onto the screen unless
  611.                   the top edge position is changed.
  612.  
  613.         LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking
  614.             on this gadget will cause the window to shrink/zoom back
  615.             to its original position. This differs from the WA_Zoom
  616.             tag behaviour. When the window zooms back to its original
  617.             position the gadgets are automatically refreshed.
  618.             Default: FALSE
  619.  
  620.         LAWN_MaxPen (LONG) - The maximum rendering pen index your code
  621.             will use. Since you are -- with some restrictions -- allowed
  622.             to render into the window created you may want to avoid
  623.             silly side effects if drawing images or other colourful
  624.             textures which do not share the common user interface colours.
  625.             By default the layout code will change the maximum rendering
  626.             pen number for the window to include only the user interface
  627.             pen colours. This can, but need not disturb your own private
  628.             window rendering.
  629.             Look up graphics.library/SetMaxPen for more information.
  630.             Default: determined by looking up Screen->DrawInfo.dri_Pens
  631.  
  632.         LAWN_BelowMouse (BOOL) - This instructs the layout routine to
  633.             centre the window created -- if possible -- below the
  634.             mouse pointer. This effectively ignores any left edge,
  635.             top edge or alignment settings.
  636.             Default: FALSE
  637.  
  638.         LAWN_MoveToWindow (BOOL) - When the window is finally open the
  639.             user interface code will try to make sure the entire window
  640.             is visible on the screen, this may involve moving the
  641.             currently visible portion of an autoscrolling screen.
  642.             Default: TRUE
  643.  
  644.         LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events
  645.             automatically.
  646.             Default: TRUE
  647.  
  648.         LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user
  649.             presses the "Help" key. See gtlayout.h for more information.
  650.             Default: NULL
  651.  
  652.         LAWN_Parent (struct Window *) - Parent window to centre the child
  653.             window in.
  654.             Default: NULL
  655.  
  656.         LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow()
  657.             until the child window is closed. NOTE: requires LAWN_Parent
  658.             attribute.
  659.             Default: FALSE
  660.  
  661.         LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created.
  662.             When in zoomed state, the window will be as small as possible,
  663.             showing only the window title and window gadgets:
  664.             NOTE: this tag implies LAWN_Zoom,TRUE
  665.             Default: FALSE
  666.  
  667.         LAWN_Title (STRPTR) - The window title to use. Use this tag in
  668.             place of WA_Title or you will break the layout code.
  669.             Default: no title
  670.  
  671.         LAWN_Bounds (struct IBox *) - Bounds to centre the window in.
  672.             Default: NULL
  673.  
  674.         LAWN_ExtraWidth (LONG) - Extra width to add into the calculation
  675.             when opening the window.
  676.             Default: 0
  677.  
  678.         LAWN_ExtraHeight (LONG) - Extra height to add into the calculation
  679.             when opening the window.
  680.             Default: 0
  681.  
  682.         LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you
  683.             will break the object handling code.
  684.  
  685.         LAWN_AlignWindow (UWORD) - Alignment information for the window, must
  686.             be a mask made from the following bit values:
  687.  
  688.                 ALIGNF_RIGHT - Align to screen right edge
  689.                 ALIGNF_LEFT - Align to screen left edge
  690.                 ALIGNF_TOP - Align to screen top edge
  691.                 ALIGNF_BOTTOM - Align to screen bottom edge
  692.  
  693.             Unless forbidden (such as by passing ALIGNF_RIGHT|ALIGNF_TOP)
  694.             the window will be centered horizontally and/or vertically.
  695.  
  696.         LAWN_FlushLeft (BOOL) - Add no horizontal space surrounding the
  697.             objects the windows will hold.
  698.             (requires gtlayout.library v10 or higher)
  699.  
  700.         LAWN_FlushTop (BOOL) - Add no vertical space surrounding the
  701.             objects the windows will hold.
  702.             (requires gtlayout.library v10 or higher)
  703.  
  704.         LAWN_Show (BOOL) - Make the window visible when it is opened;
  705.             this may involve depth-arranging screens.
  706.             (requires gtlayout.library v10 or higher)
  707.  
  708.    RESULT
  709.  
  710.         Window - Pointer to a Window structure.
  711.  
  712.    SEE ALSO
  713.  
  714.        intuition.library/OpenWindow
  715.        intuition.library/OpenWindowTagList
  716. gtlayout.library/LT_CreateHandleTagList gtlayout.library/LT_CreateHandleTaglist
  717.  
  718.    NAME
  719.  
  720.         LT_CreateHandleTagList -- Allocate auxilary data required by LT_New()
  721.                                   and LT_BuildA().
  722.  
  723.    SYNOPSIS
  724.  
  725.         Handle = LT_CreateHandleTagList(Screen,Tags);
  726.           D0                              A0    A1
  727.  
  728.         LayoutHandle *LT_CreateHandleTagList(struct Screen *,struct TagItem *);
  729.  
  730.         Handle = LT_CreateHandleTags(Screen,...);
  731.  
  732.         struct LayoutHandle *LT_CreateHandleTags(struct Screen *,...);
  733.  
  734.    FUNCTION
  735.  
  736.         Memory is allocated, tables are set up and data is collected
  737.         on a screen a user interface is to be opened on. This
  738.         involves calculating the screen font parameters.
  739.  
  740.    INPUTS
  741.  
  742.         Screen - Pointer to the screen the user interface is to
  743.                  use. Passing NULL will cause the default public
  744.                  screen to be used.
  745.  
  746.                  NOTE: if NULL is passed the default public screen
  747.                        will stay locked until LT_DeleteHandle()
  748.                        is called.
  749.  
  750.         Tags - Tag values to control certain aspects of the
  751.                user interface created.
  752.  
  753.    TAGS
  754.  
  755.         LH_AutoActivate (BOOL) - Set to TRUE if you want the interface
  756.             to always keep a string gadget active if possible. Hitting
  757.             the return key will then cause the next following string
  758.             gadget to get activated, either cycling through all the
  759.             string gadgets available or stopping at the next string
  760.             gadget to have the LAST_LastGadget attribute set.
  761.             Default: TRUE
  762.  
  763.         LH_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  764.             events.
  765.             Default: TRUE
  766.             (requires gtlayout.library v13 or higher)
  767.  
  768.         LH_UserData (APTR) - Store user specific data in the
  769.             LayoutHandle->UserData entry.
  770.  
  771.             NOTE: This tag requires gtlayout.library v9 and the
  772.                   corresponding entry in the LayoutHandle exists
  773.                   only under gtlayout.library v9 and up. *NEVER*
  774.                   write to this entry, use LT_SetAttributes()
  775.                   instead.
  776.  
  777.         LH_LocaleHook (struct Hook *) - The hook to call when
  778.             locale string IDs are to be mapped to strings. The
  779.             hook function is called with the following parameters:
  780.  
  781.             String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  782.               D0                            A0                         A2
  783.                               LONG ID)
  784.                                    A1
  785.  
  786.             The function is to look up the string associated with the ID
  787.             passed in and return the string.
  788.             Default: no locale hook
  789.  
  790.         LH_Font (struct TTextAttr *) - The text font to use when creating
  791.             the gadgets and objects.
  792.             Default: Screen->Font
  793.  
  794.         LH_CloningPermitted (BOOL) - If a window will not fit onto the
  795.             screen the user interface is intended for, the layout engine
  796.             will scale the interface data down while stepping down in
  797.             font size. If all this fails, the engine will open a custom
  798.             screen for the window; this process is called "cloning".
  799.             The LH_CloningPermitted tag controls whether the engine will
  800.             actually try to open the custom screen or just return NULL
  801.             when LT_Build fails.
  802.             Default: TRUE
  803.  
  804.         LH_EditHook (struct Hook *) - You can specify a default string
  805.             gadget editing hook to be used for all following string
  806.             gadgets. Your hook should obey the same rules that apply
  807.             to hooks passed via GTST_EditHook/GTIN_EditHook.
  808.             Default: NULL
  809.  
  810.         LH_ExactClone (BOOL) - This tag works in conjunction with the
  811.             LH_CloningPermitted tag. By default the layout engine will
  812.             try to replicate only the basic characteristics of the
  813.             screen the window was intended to open on. This may result
  814.             in a screen which uses less colours than the original
  815.             screen. You can force the engine to make an almost exact
  816.             clone of the original screen by passing the LH_ExactClone
  817.             tag with a value of TRUE.
  818.             Default: FALSE
  819.  
  820.         LH_MenuGlyphs (BOOL) - This tag will make the layout engine
  821.             fill in the AmigaGlyph and CheckGlyph entries of the
  822.             LayoutHandle if running under Kickstart 3.0 or higher.
  823.             The corresponding images will be scaled to fit the actual
  824.             screen aspect ratio values and can later be used for
  825.             menu layout.
  826.             Default: FALSE
  827.  
  828.         LH_Parent (struct Window *) - You can pass a pointer to the
  829.             parent window of the window you intend to open using
  830.             the user interface layout engine. The new window will
  831.             open inside the boundaries of the parent window. If the
  832.             size does not fit, it will be opened centered over the
  833.             parent window.
  834.             Default: NULL
  835.  
  836.         LH_BlockParent (BOOL) - This tag works in conjunction with the
  837.             LH_Parent tag. If in effect, will block the parent window
  838.             via LT_LockWindow until the new window is closed, after
  839.             which the parent window is unlocked again.
  840.             Default: FALSE
  841.  
  842.         LH_SimpleClone (BOOL) - This tag works in conjunction with the
  843.             LH_CloningPermitted tag. It will make the layout engine
  844.             forget most information about the original screen the
  845.             user interface was intended for. In short, it will open a
  846.             simple default screen for the interface.
  847.             Default: FALSE
  848.  
  849.         LH_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  850.             of with LT_DeleteHandle() all variables maintained by the
  851.             input handling code will be flushed. For example, if you
  852.             would use the LA_STRPTR tag for STRING_KIND objects the
  853.             last string gadget contents would be copied into the buffer
  854.             pointed to by LA_STRPTR. If you do not want to use this
  855.             feature, disable it with "LH_ExitFlush,FALSE".
  856.             Default: TRUE
  857.  
  858.             (requires gtlayout.library v9 or higher)
  859.  
  860.    RESULT
  861.  
  862.         Handle - Pointer to a LayoutHandle structure.
  863. gtlayout.library/LT_DeleteHandle              gtlayout.library/LT_DeleteHandle
  864.  
  865.    NAME
  866.  
  867.         LT_DeleteHandle -- Release storage space allocated by
  868.                            LT_CreateHandleTagList, closing windows,
  869.                            removing gadgets, etc.
  870.  
  871.    SYNOPSIS
  872.  
  873.         LT_DeleteHandle(Handle);
  874.                           A0
  875.  
  876.         VOID LT_DeleteHandle(LayoutHandle *);
  877.  
  878.    FUNCTION
  879.  
  880.         Windows and gadgets created by LT_CreateHandleTagList()
  881.         are removed, any associated memory is deallocated.
  882.  
  883.    INPUTS
  884.  
  885.         Handle - Pointer to a LayoutHandle structure created
  886.                  by LT_CreateHandleTaglist(). Passing NULL is
  887.                  harmless.
  888.  
  889.    RESULT
  890.  
  891.         none
  892.  
  893.    SEE ALSO
  894.  
  895.         gtlayout.library/CreateHandleTagList
  896. gtlayout.library/LT_DeleteWindowLock      gtlayout.library/LT_DeleteWindowLock
  897.  
  898.    NAME
  899.  
  900.         LT_DeleteWindowLock -- Remove all locks from a window
  901.  
  902.    SYNOPSIS
  903.  
  904.         LT_DeleteWindowLock(Window);
  905.                               A0
  906.  
  907.         VOID LT_DeleteWindowLock(struct Window *);
  908.  
  909.    FUNCTION
  910.  
  911.         Before closing a locked window you should call this routine
  912.         which will remove all outstanding locks from it.
  913.  
  914.    INPUTS
  915.  
  916.         Window - Pointer to window structure.
  917.  
  918.    RESULT
  919.  
  920.         none
  921. gtlayout.library/LT_DisposeMenu              gtlayout.library/LT_DisposeMenu
  922.  
  923.    NAME
  924.  
  925.         LT_DisposeMenu -- Release storage space allocated by
  926.                           LT_NewMenuTemplate or LT_NewMenuTagList (V11)
  927.  
  928.    SYNOPSIS
  929.  
  930.         LT_DisposeMenu(Menu)
  931.                         A0
  932.  
  933.         VOID LT_DisposeMenu(struct Menu *);
  934.  
  935.    FUNCTION
  936.  
  937.         Menus and MenuItems allocated by LT_NewMenuTemplate or
  938.         LT_NewMenuTagList are deallocated.
  939.  
  940.    INPUTS
  941.  
  942.         Menu - Pointer to Menu structure as returned by
  943.                LT_NewMenuTemplate or LT_NewMenuTagList. Passing
  944.                NULL is harmless.
  945.  
  946.    RESULT
  947.  
  948.         none
  949.  
  950.    SEE ALSO
  951.  
  952.         gtlayout.library/LT_NewMenuTagList
  953.         gtlayout.library/LT_NewMenuTemplate
  954. gtlayout.library/LT_EndGroup                      gtlayout.library/LT_EndGroup
  955.  
  956.    NAME
  957.  
  958.         LT_EndGroup -- end a group declaration.
  959.  
  960.    SYNOPSIS
  961.  
  962.         LT_EndGroup(Handle);
  963.                      A0
  964.  
  965.         VOID LT_EndGroup(LayoutHandle *);
  966.  
  967.    FUNCTION
  968.  
  969.        This is just a short form of
  970.  
  971.            LT_New(Handle,
  972.                LA_Type, END_KIND,
  973.            TAG_DONE);
  974.  
  975.        It helps to save (some) space.
  976.  
  977.    INPUTS
  978.  
  979.        Handle - Pointer to LayoutHandle.
  980.  
  981.    RESULT
  982.  
  983.        none
  984. gtlayout.library/LT_EndRefresh                  gtlayout.library/LT_EndRefresh
  985.  
  986.    NAME
  987.  
  988.         LT_EndRefresh -- Optimized window refreshing
  989.  
  990.    SYNOPSIS
  991.  
  992.         LT_EndRefresh(Handle)
  993.                         A0
  994.  
  995.         VOID LT_EndRefresh(LayoutHandle *);
  996.  
  997.    FUNCTION
  998.  
  999.         If you wish to handle window refreshing all on your own, you
  1000.         might want to use the LT_BeginRefresh...LT_EndRefresh pair
  1001.         in your program. By default the user interface layout engine
  1002.         will automatically intercept IDCMP_REFRESHWINDOW events and
  1003.         react to them accordingly.
  1004.  
  1005.    INPUTS
  1006.  
  1007.         Handle - Pointer to a LayoutHandle structure.
  1008.  
  1009.    RESULT
  1010.  
  1011.         none.
  1012.  
  1013.    SEE ALSO
  1014.  
  1015.         intuition.library/BeginRefresh
  1016.         intuition.library/EndRefresh
  1017.         gtlayout.library/LT_BeginRefresh
  1018. gtlayout.library/LT_Exit                              gtlayout.library/LT_Exit
  1019.  
  1020.    NAME
  1021.  
  1022.         LT_Exit -- Clean up user interface allocations
  1023.  
  1024.    SYNOPSIS
  1025.  
  1026.         LT_Exit();
  1027.  
  1028.         VOID LT_Exit(VOID);
  1029.  
  1030.    FUNCTION
  1031.  
  1032.         When you are finished with user interface creation and
  1033.         do not not need the code any more you should call this
  1034.         routine. It will free all the memory allocated by
  1035.         LT_Init(), close libraries, etc.
  1036.  
  1037.    INPUTS
  1038.  
  1039.         none
  1040.  
  1041.    RESULT
  1042.  
  1043.         none
  1044.  
  1045.    NOTES
  1046.  
  1047.         This routine is available in the link library only.
  1048. gtlayout.library/LT_FindMenuCommand          gtlayout.library/LT_FindMenuCommand
  1049.  
  1050.    NAME
  1051.  
  1052.         LT_FindMenuCommand -- Get the menu/submenu item associated
  1053.                               with a rawkey event (V11)
  1054.  
  1055.    SYNOPSIS
  1056.  
  1057.         Item = LT_FindMenuCommand(Menu,Code,Qualifier,Gadget)
  1058.          D0                        A0  D0       D0      A1
  1059.  
  1060.         struct MenuItem *LT_FindMenuCommand(struct Menu *,
  1061.  
  1062.                              UWORD,ULONG,struct Gadget *);
  1063.  
  1064.    FUNCTION
  1065.  
  1066.         With the IntuiMessage data copied from a type IDCMP_RAWKEY message
  1067.         tries to find the MenuItem the event referred to.
  1068.  
  1069.    INPUTS
  1070.  
  1071.         Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1072.  
  1073.         Code - Value copied from IntuiMessage->Code
  1074.  
  1075.         Qualifier - Value copied from IntuiMessage->Qualifier
  1076.  
  1077.         Gadget - Value copied from IntuiMessage->IAddress
  1078.  
  1079.    RESULT
  1080.  
  1081.         Item - Pointer to the struct MenuItem * in question or NULL
  1082.                if none could be found
  1083.  
  1084.    SEE ALSO
  1085.  
  1086.         gtlayout.library/LT_NewMenuTagList
  1087. gtlayout.library/LT_Fixed2String              gtlayout.library/LT_Fixed2String
  1088.  
  1089.    NAME
  1090.  
  1091.         LT_Fixed2String -- Convert a fixed-point number into an alphanumeric
  1092.                            string.
  1093.  
  1094.    SYNOPSIS
  1095.  
  1096.         LT_Fixed2String(Fixed,String);
  1097.                           D0    D1
  1098.  
  1099.         VOID LT_Fixed2String(FIXED,STRPTR);
  1100.  
  1101.    FUNCTION
  1102.  
  1103.         This routine implements a service similar to ftoa(). It converts
  1104.         a fixed point number into an ASCII representation.
  1105.  
  1106.    INPUTS
  1107.  
  1108.         Fixed - Fixed point numeric value
  1109.  
  1110.         String - Buffer to receive the converted value. This buffer
  1111.                  must be at least 12 bytes large.
  1112.  
  1113.    NOTES
  1114.  
  1115.         The decimal point will be taken from the current locale.
  1116.         If locale.library is not installed in your system, the
  1117.         `.' character will be used instead.
  1118.  
  1119.         The arguments are passed in D0 and D1, this is *not* a
  1120.         typo.
  1121.  
  1122.    SEE ALSO
  1123.  
  1124.         gtlayout.library/LT_String2Fixed
  1125. gtlayout.library/LT_FixedMult                    gtlayout.library/LT_FixedMult
  1126.  
  1127.    NAME
  1128.  
  1129.         LT_FixedMult -- Multiply a fixed-point number with an integer value.
  1130.  
  1131.    SYNOPSIS
  1132.  
  1133.         Fixed = LT_FixedMult(Fixed,Factor)
  1134.           D0                   D0    D1
  1135.  
  1136.         FIXED LT_FixedMult(FIXED,ULONG);
  1137.  
  1138.    FUNCTION
  1139.  
  1140.         The layout engine provides only a fixed point multiplication
  1141.         routine. You need to implement other numeric operations on
  1142.         your own.
  1143.  
  1144.    INPUTS
  1145.  
  1146.         Fixed - Fixed-point number to be multiplied.
  1147.  
  1148.         Factor - Integer value to multiply fixed-point number
  1149.                  with.
  1150.  
  1151.    RESULT
  1152.  
  1153.         Fixed - Product
  1154. gtlayout.library/LT_GetAttributesA          gtlayout.library/LT_GetAttributesA
  1155.  
  1156.    NAME
  1157.  
  1158.         LT_GetAttributesA -- Inquire information on a gadget.
  1159.  
  1160.    SYNOPSIS
  1161.  
  1162.         Value = LT_GetAttributesA(Handle,ID,Tags);
  1163.           D0                        A0   D0  A1
  1164.  
  1165.         LONG LT_GetAttributesA(LayoutHandle *,LONG ID,struct TagItem *);
  1166.  
  1167.         Value = LT_GetAttributes(Handle,ID,...);
  1168.  
  1169.         LONG LT_GetAttributes(LayoutHandle *,LONG ID,...);
  1170.  
  1171.    FUNCTION
  1172.  
  1173.         All objects created by the user interface layout code posess
  1174.         certain unique properties. The LT_GetAttributes() function will
  1175.         will inquire this information and return it. The implementation
  1176.         differs from gadtools.library/GT_GetGadgetAttrs in that you
  1177.         can inquire only a small subset of the object properties possible
  1178.         via the taglist passed in.
  1179.  
  1180.    INPUTS
  1181.  
  1182.         Handle - Pointer to LayoutHandle structure.
  1183.  
  1184.         ID - ID number of the object to inquire information about. This
  1185.              is the same value you passed via LA_ID to LT_New() when
  1186.              you created this object.
  1187.  
  1188.         Tags - TagItem list to receive information about the object
  1189.                in question.
  1190.  
  1191.    TAGS
  1192.  
  1193.         LA_Left (LONG *) - Left edge of object.
  1194.  
  1195.         LA_Top (LONG *) - Top edge of object.
  1196.  
  1197.         LA_Width (LONG *) - Width of object.
  1198.  
  1199.         LA_Height (LONG *) - Height of object.
  1200.  
  1201.         LA_Chars (LONG *) - Width of object measured in character
  1202.            widths.
  1203.            (requires gtlayout.library v9 or higher)
  1204.  
  1205.         LA_Lines (LONG *) - Height of object measured in character
  1206.            heights.
  1207.            (requires gtlayout.library v9 or higher)
  1208.  
  1209.         LA_LabelLeft (LONG *) - Left edge of label text.
  1210.            (requires gtlayout.library v9 or higher)
  1211.  
  1212.         LA_LabelTop (LONG *) - Top edge of label text.
  1213.            (requires gtlayout.library v9 or higher)
  1214.  
  1215.         LABO_Object (Object *) - Returns a pointer to the BOOPSI object
  1216.            the BOOPSI_KIND object is based upon.
  1217.  
  1218.            NOTE: Don't unlink the object or dispose of it or terrible
  1219.                  things are bound to happen.
  1220.  
  1221.            (requires gtlayout.library v10 or higher)
  1222.  
  1223.    RESULT
  1224.  
  1225.         The result depends on the object type:
  1226.  
  1227.             VERTICAL_KIND:
  1228.             HORIZONTAL_KIND:
  1229.  
  1230.                 active page
  1231.  
  1232.             FRACTION_KIND:
  1233.  
  1234.                 current LAFC_Number value
  1235.  
  1236.             SCROLLER_KIND:
  1237.  
  1238.                 current GTSC_Top value
  1239.  
  1240.             TAPEDECK_KIND:
  1241.  
  1242.                 current LATD_Pressed value
  1243.  
  1244.             LEVEL_KIND:
  1245.  
  1246.                 current LAVL_Level state
  1247.  
  1248.             CHECKBOX_KIND:
  1249.  
  1250.                 current GTCB_Checked state
  1251.  
  1252.             LISTVIEW_KIND:
  1253.  
  1254.                 current GTLV_Selected state
  1255.  
  1256.             MX_KIND:
  1257.  
  1258.                 current GTMX_Active state
  1259.  
  1260.             CYCLE_KIND:
  1261.  
  1262.                 current GTCY_Active state
  1263.  
  1264.             PALETTE_KIND:
  1265.  
  1266.                 current GTPA_Color state
  1267.  
  1268.             SLIDER_KIND:
  1269.  
  1270.                 current GTSL_Level state
  1271.  
  1272.             GAUGE_KIND:
  1273.  
  1274.                 current LAGA_Percent state
  1275.  
  1276.             STRING_KIND:
  1277.  
  1278.                 pointer to current string
  1279.  
  1280.             PASSWORD_KIND:
  1281.  
  1282.                 pointer to current string
  1283.  
  1284.             INTEGER_KIND:
  1285.  
  1286.                 number currently entered
  1287.  
  1288.             BOOPSI_KIND:
  1289.  
  1290.                 whatever the object thinks is its
  1291.                 current value
  1292. gtlayout.library/LT_GetCode                        gtlayout.library/LT_GetCode
  1293.  
  1294.    NAME
  1295.  
  1296.         LT_GetCode -- Easy raw key event to ANSI conversion.
  1297.  
  1298.    SYNOPSIS
  1299.  
  1300.         Key = LT_GetCode(Qualifier,Class,Code,Gadget);
  1301.          D0                  D0     D1    D2    A0
  1302.  
  1303.         WORD LT_GetCode(ULONG,ULONG,UWORD,struct Gadget *);
  1304.  
  1305.    FUNCTION
  1306.  
  1307.         The user interface layout engine can convert IDCMP_RAWKEY
  1308.         events into ANSI codes. Pass in the data you copied from
  1309.         the IntuiMessage here.
  1310.  
  1311.    INPUTS
  1312.  
  1313.         Qualifier - Copied from IntuiMessage->Qualifier
  1314.  
  1315.         Class - Copied from IntuiMessage->Class
  1316.  
  1317.         Code - Copied from IntuiMessage->Code
  1318.  
  1319.         Gadget - Copied from IntuiMessage->IAddress
  1320.  
  1321.    RESULT
  1322.  
  1323.         Key - ANSI code generated from the input data
  1324.               or -1 if no such code was to be generated.
  1325. gtlayout.library/LT_GetMenuItem          gtlayout.library/LT_GetMenuItem
  1326.  
  1327.    NAME
  1328.  
  1329.         LT_GetMenuItem -- Get the menu/submenu item associated with an ID (V11)
  1330.  
  1331.    SYNOPSIS
  1332.  
  1333.         Item = LT_GetMenuItem(Menu,ID)
  1334.          D0                    A0  D0
  1335.  
  1336.         struct MenuItem *LT_GetMenuItem(struct Menu *,ULONG);
  1337.  
  1338.    FUNCTION
  1339.  
  1340.         This routine scans through all menu items associated with the
  1341.         menu and returns a pointer to the item associated with the
  1342.         given ID value.
  1343.  
  1344.    INPUTS
  1345.  
  1346.         Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1347.  
  1348.         ID - Unique ID of the item to find.
  1349.  
  1350.    RESULT
  1351.  
  1352.         Item - Pointer to the struct MenuItem * in question or NULL
  1353.                if none could be found
  1354.  
  1355.    SEE ALSO
  1356.  
  1357.         gtlayout.library/LT_NewMenuTagList
  1358. gtlayout.library/LT_GetIMsg                        gtlayout.library/LT_GetIMsg
  1359.  
  1360.    NAME
  1361.  
  1362.         LT_GetIMsg -- Retrieve the next pending IntuiMessage
  1363.                       from the window associated with a
  1364.                       LayoutHandle.
  1365.  
  1366.    SYNOPSIS
  1367.  
  1368.         IntuiMessage = LT_GetIMsg(Handle);
  1369.              D0                     A0
  1370.  
  1371.         struct IntuiMessage *LT_GetIMsg(LayoutHandle *);
  1372.  
  1373.    FUNCTION
  1374.  
  1375.         This routine will handle most of the input loop for
  1376.         you. Just pass the pointer to the layout handle in,
  1377.         check if the result code is non-null, copy the data
  1378.         you need and reply the message via LT_ReplyIMsg().
  1379.  
  1380.         You will still need to wait for new input, as LT_GetIMsg
  1381.         will poll the MsgPort of the window.
  1382.  
  1383.         LT_GetIMsg() will try its best to distinguish between
  1384.         different LayoutHandles sharing the same Window->UserPort.
  1385.         If it finds that the window the message was sent to is
  1386.         using a different LayoutHandle, it will switch to using
  1387.         this handle (V13).
  1388.  
  1389.    INPUTS
  1390.  
  1391.         Handle - Pointer to LayoutHandle structure
  1392.  
  1393.    RESULT
  1394.  
  1395.         IntuiMessage - Pointer to IntuiMessage structure
  1396.  
  1397.    NOTES
  1398.  
  1399.         You *must not* make any assumptions about the contents
  1400.         of the IntuiMessage structure except for the following
  1401.         entries:
  1402.  
  1403.            Class
  1404.            Code
  1405.            Qualifier
  1406.            IAddress
  1407.  
  1408.         When finished, you must dispose the IntuiMessage via
  1409.         LT_ReplyIMsg or memory will be lost which can never
  1410.         be reclaimed.
  1411.  
  1412.         DO NOT CALL LT_HandleInput() ON THE DATA YOU RECEIVE
  1413.         FROM LT_GetIMsg() AS LT_GetIMsg() ALREADY DOES ALL THE
  1414.         MAGIC LT_HandleInput() OTHERWISE WOULD NEED TO DO!
  1415.         IF YOU STILL DO CALL LT_HandleInput() ON THE DATA YOU
  1416.         WILL RECEIVE `GHOST' EVENTS.
  1417.  
  1418.    SEE ALSO
  1419.  
  1420.         gtlayout.library/LT_ReplyIMsg
  1421. gtlayout.library/LT_HandleInput                gtlayout.library/LT_HandleInput
  1422.  
  1423.    NAME
  1424.  
  1425.         LT_HandleInput -- Filter IntuiMessage data.
  1426.  
  1427.    SYNOPSIS
  1428.  
  1429.         LT_HandleInput(Handle,Qualifier,Class,Code,Gadget);
  1430.                          A0      A1      A2    A2    A3
  1431.  
  1432.         VOID LT_HandleInput(LayoutHandle *,ULONG,ULONG *,
  1433.                             UWORD *,struct Gadget **);
  1434.  
  1435.    FUNCTION
  1436.  
  1437.         In order to keep track of user interface actions, such as
  1438.         keys getting pressed, sliders getting moved, etc. your
  1439.         code is to call LT_HandleInput() with data copied from the
  1440.         IntuiMessage it has just received and replied.
  1441.  
  1442.         NOTE: do not call this routine before you have actually
  1443.               replied the IntuiMessage received or weird things
  1444.               may happen.
  1445.  
  1446.    INPUTS
  1447.  
  1448.         Handle - Pointer to a LayoutHandle structure.
  1449.  
  1450.         Qualifier - The Qualifier value copied from the
  1451.                     IntuiMessage structure.
  1452.  
  1453.         Class - Pointer to the ULONG variable which holds the
  1454.                 value copied from the Class entry of the
  1455.                 IntuiMessage structure.
  1456.  
  1457.         Code - Pointer to the UWORD variable which holds the
  1458.                value copied from the Code entry of the
  1459.                IntuiMessage structure.
  1460.  
  1461.         Gadget - Pointer to the Gadget value copied from the
  1462.                  IAddress entry of the IntuiMessage structure.
  1463.  
  1464.    WARNING
  1465.  
  1466.         For BOOPSI_KIND objects keystroke activation may lead to
  1467.         unexpected results. Your application will hear a IDCMP_GADGETUP
  1468.         event, the IntuiMessage->Code value will hold the ANSI key
  1469.         code of the key the user pressed.
  1470.  
  1471.    EXAMPLE
  1472.  
  1473.         struct IntuiMessage *IntuiMessage;
  1474.         ULONG Qualifier,Class;
  1475.         UWORD Code;
  1476.         struct Gadget *Gadget;
  1477.  
  1478.         for(;;)
  1479.         {
  1480.             WaitPort(Window -> UserPort);
  1481.  
  1482.             while(IntuiMessage = GT_GetIMsg(Window -> UserPort))
  1483.             {
  1484.                 Class = IntuiMessage -> Class;
  1485.                 Code = IntuiMessage -> Code;
  1486.                 Qualifier = IntuiMessage -> Qualifier;
  1487.                 Gadget = IntuiMessage -> Gadget;
  1488.  
  1489.                 GT_ReplyIMsg(IntuiMessage);
  1490.  
  1491.                 LT_HandleInput(Handle,Qualifier,&Class,&Code,&Gadget);
  1492.             }
  1493.         }
  1494.  
  1495.    RESULT
  1496.  
  1497.         none
  1498. gtlayout.library/LT_Init                              gtlayout.library/LT_Init
  1499.  
  1500.    NAME
  1501.  
  1502.         LT_Init -- Initialize user interface code.
  1503.  
  1504.    SYNOPSIS
  1505.  
  1506.         LT_Init();
  1507.  
  1508.         VOID LT_Init(VOID);
  1509.  
  1510.    FUNCTION
  1511.  
  1512.         You need to initialize the user interface code only once,
  1513.         so it can set up its internals, open libraries, etc.
  1514.         The code has to be initialized before any user interface
  1515.         creation can take place.
  1516.  
  1517.    INPUTS
  1518.  
  1519.         none
  1520.  
  1521.    RESULT
  1522.  
  1523.         none
  1524.  
  1525.    NOTES
  1526.  
  1527.         This routine is available in the link library only.
  1528. gtlayout.library/LT_LabelChars                  gtlayout.library/LT_LabelChars
  1529.  
  1530.    NAME
  1531.  
  1532.         LT_LabelChars -- Calculate the width of a a string
  1533.                          according to the user interface font
  1534.                          associated with a LayoutHandle.
  1535.  
  1536.    SYNOPSIS
  1537.  
  1538.         Length = LT_LabelChars(Handle,Label);
  1539.           D0                     A0    A1
  1540.  
  1541.         LONG LT_LabelChars(struct LayoutHandle *,STRPTR);
  1542.  
  1543.    FUNCTION
  1544.  
  1545.         Calculates the width of a string according to the user
  1546.         interface font used. The width is then converted to a number
  1547.         of characters suitable for using with the LA_Chars tag
  1548.         item when calling LT_New().
  1549.  
  1550.         You can pass multi-line label texts to this routine,
  1551.         it will calculate the maximum length of the single
  1552.         lines. (V12)
  1553.  
  1554.    INPUTS
  1555.  
  1556.         Handle - Pointer to LayoutHandle structure.
  1557.  
  1558.         Label - Pointer to string.
  1559.  
  1560.    RESULT
  1561.  
  1562.         Length - Number of characters that are considered
  1563.             equivalent to the string length in pixels.
  1564. gtlayout.library/LT_LabelWidth                  gtlayout.library/LT_LabelWidth
  1565.  
  1566.    NAME
  1567.  
  1568.         LT_LabelWidth -- Calculate the width of a string according
  1569.                          to the user interface font used.
  1570.  
  1571.    SYNOPSIS
  1572.  
  1573.         Width = LT_LabelWidth(Handle,Label);
  1574.           D0                    A0    A1
  1575.  
  1576.         LONG LT_LabelWidth(LayoutHandle *,STRPTR);
  1577.  
  1578.    FUNCTION
  1579.  
  1580.         This routine calculates the width of strings in
  1581.         terms of pixels according to the user interface
  1582.         font associated with the LayoutHandle.
  1583.  
  1584.         You can pass multi-line label texts to this routine,
  1585.         it will calculate the maximum length of the single
  1586.         lines. (V12)
  1587.  
  1588.    INPUTS
  1589.  
  1590.         Handle - Pointer to LayoutHandle structure.
  1591.  
  1592.    RESULT
  1593.  
  1594.         Width - Width of the text string in pixels.
  1595. gtlayout.library/LT_LayoutMenusA              gtlayout.library/LT_LayoutMenusA
  1596.  
  1597.    NAME
  1598.  
  1599.         LT_LayoutMenusA -- Create a menu according to a template.
  1600.  
  1601.    SYNOPSIS
  1602.  
  1603.         Menu = LT_LayoutMenusA(Handle,Template,Tags);
  1604.          D0                      A0     A1      A2
  1605.  
  1606.         struct Menu *LT_LayoutMenusA(LayoutHandle *,struct NewMenu *,struct TagItem *);
  1607.  
  1608.         Menu = LT_LayoutMenus(Handle,Template,...);
  1609.  
  1610.         struct Menu *LT_LayoutMenus(LayoutHandle *,struct NewMenu *,...);
  1611.  
  1612.    FUNCTION
  1613.  
  1614.         Unlike the corresponding routines in gadtools.library
  1615.         LT_LayoutMenusA() will both create and layout a menu.
  1616.         Also included is locale support.
  1617.  
  1618.    INPUTS
  1619.  
  1620.         Handle - Pointer to LayoutHandle structure.
  1621.  
  1622.         Template - Address of a ready-to-use NewMenu table to
  1623.             create the menu from.
  1624.  
  1625.         Tags - Tagitem list to control menu attributes
  1626.  
  1627.    TAGS
  1628.  
  1629.         LAMN_FirstLabel (LONG) - Locale ID of the first string to
  1630.             use as a menu title/item/subitem label. This tag
  1631.             works in conjunction with LA_LastLabel.
  1632.  
  1633.         LAMN_LastLabel (LONG) - Locale ID of the last string to
  1634.             use as a menu title/item/subitem label. This tag
  1635.             works in conjunction with LA_FirstLabel. The code
  1636.             will loop through FirstLabel..LastLabel and assign
  1637.             the corresponding locale text for each ID to the
  1638.             NewMenu.nm_Label entries. Labels which are already
  1639.             initialized with NM_BARLABEL are skipped.
  1640.  
  1641.         LAMN_LabelTable (LONG *) - Pointer to an array of IDs
  1642.             to use for building the menu labels. This requires
  1643.             that a locale hook is provided with the layout handle.
  1644.             The array is terminated by -1.
  1645.  
  1646.    NOTES
  1647.  
  1648.         If you created the LayoutHandle with the LH_MenuGlyphs,TRUE
  1649.         attribute, the menu will use the scaled menu glyphs.
  1650.  
  1651.    RESULT
  1652.  
  1653.         Menu - Pointer to a Menu structure. You can free this
  1654.                using gadtools.library/FreeMenus().
  1655. gtlayout.library/LT_LevelWidth                   gtlayout.library/LT_LevelWidth
  1656.  
  1657.    NAME
  1658.  
  1659.         LT_LevelWidth -- Determine the maximum width of a SLIDER_KIND
  1660.                          level string.
  1661.  
  1662.    SYNOPSIS
  1663.  
  1664.         Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  1665.           D0                    A0        A1         A2     D0  D1    A3
  1666.  
  1667.                                   MaxLen,FullCheck);
  1668.                                     A5      D2
  1669.  
  1670.         LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  1671.                            LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  1672.                            LONG *,BOOL);
  1673.  
  1674.    FUNCTION
  1675.  
  1676.         In order to make room for the level text displayed by a
  1677.         SLIDER_KIND object one needs to know how much space the
  1678.         longest level string will occupy. Otherwise, the level
  1679.         text may overwrite the gadget label text or the slider
  1680.         container. This routine will rattle through all possible
  1681.         slider settings (as given via the Min and the Max
  1682.         level values) and determine the longest label string
  1683.         according to the font used.
  1684.  
  1685.    INPUTS
  1686.  
  1687.         Handle - Pointer to a LayoutHandle structure, as returned by
  1688.                  a call to LT_CreateHandleTags().
  1689.  
  1690.         FormatString - The sprintf() style formatting string to be used
  1691.                        to format the slider level settings into text.
  1692.                        This is the same string you would pass in via
  1693.                        the GTSL_LevelFormat tag when creating the
  1694.                        slider object.
  1695.                        Default: "%lD" for systems which have locale.library
  1696.                                 installed, "%ld" otherwise.
  1697.  
  1698.         DispFunc - A pointer to the function to filter the slider level
  1699.                    values. The result of this function will then be
  1700.                    used to format a string into the slider level text.
  1701.                    This is the same parameter you would pass in via
  1702.                    the GTSL_DispFunc tag when creating the slider
  1703.                    object.
  1704.  
  1705.                    NOTE: the routine will be called with a NULL Gadget
  1706.                          parameter, make sure your code will handle
  1707.                          this nicely.
  1708.  
  1709.                    Default: no display function
  1710.  
  1711.         Min - The smallest value the slider can be set to. This is
  1712.               same value you would pass in via GTSL_Min when creating
  1713.               the slider object.
  1714.  
  1715.         Max - The largest value the slider can be set to. This is
  1716.               same value you would pass in via GTSL_Max when creating
  1717.               the slider object.
  1718.  
  1719.         MaxWidth - Pointer to a place to store the width of the
  1720.                    longest level string in pixels. If you pass
  1721.                    in NULL instead of the address of a variable
  1722.                    no harm will be done.
  1723.  
  1724.         MaxLen - Pointer to a place to store the length of the
  1725.                  longest level string in characters. If you pass
  1726.                  in NULL instead of the address of a variable
  1727.                  no harm will be done.
  1728.  
  1729.  
  1730.         FullCheck - TRUE will cause the code to rattle through all
  1731.                     possible slider settings, starting from the
  1732.                     minimum value, ending at the maximum value.
  1733.                     While this may be a good idea for a display
  1734.                     function to map slider levels to text strings
  1735.                     of varying length it might be a problem when
  1736.                     it comes to display a range of numbers from
  1737.                     1 to 40,000: the code will loop through
  1738.                     40,000 iterations trying to find the longest
  1739.                     string.
  1740.  
  1741.                     FALSE will cause the code to calculate the
  1742.                     longest level string based only on the
  1743.                     minimum and the maximum value to check.
  1744.                     While this is certainly a good a idea when
  1745.                     it comes to display a range of numbers from
  1746.                     1 to 40,000 as only two values will be
  1747.                     checked the code may fail to produce
  1748.                     accurate results for sliders using display
  1749.                     functions mapping slider levels to strings.
  1750.  
  1751.     RESULT
  1752.  
  1753.         Index - The slider level which gives the longest
  1754.                 level string.
  1755. gtlayout.library/LT_LockWindow                  gtlayout.library/LT_LockWindow
  1756.  
  1757.    NAME
  1758.  
  1759.         LT_LockWindow -- Block user access to a window.
  1760.  
  1761.    SYNOPSIS
  1762.  
  1763.         LT_LockWindow(Window);
  1764.                         A0
  1765.  
  1766.         VOID LT_LockWindow(struct Window *);
  1767.  
  1768.    FUNCTION
  1769.  
  1770.         The window will get a wait mouse pointer attached and a blank
  1771.         Requester, preventing any user gadgets from getting used. The
  1772.         window minimum and maximum sizes are set to the current window
  1773.         size so the user will be unable to resize the window or click
  1774.         on the zoom gadget.
  1775.         This routine nests, multiple calls to LT_LockWindow() using the
  1776.         same window will increment a usage counter, so exactly the
  1777.         same number of calls to LT_UnlockWindow() will be required to
  1778.         unlock the window.
  1779.  
  1780.    INPUTS
  1781.  
  1782.         Window - Pointer to window structure.
  1783.  
  1784.    RESULT
  1785.  
  1786.         none
  1787.  
  1788.    NOTES
  1789.  
  1790.          Do not close the window you have locked unless all the
  1791.          outstanding locks are freed or memory will be lost which
  1792.          can never be reclaimed.
  1793. gtlayout.library/LT_MenuControlTagList          gtlayout.library/LT_MenuControlTagList
  1794.  
  1795.    NAME
  1796.  
  1797.         LT_MenuControlTagList -- Manipulate menus, menu/submenu items (V11)
  1798.  
  1799.    SYNOPSIS
  1800.  
  1801.         LT_MenuControlTagList(Window,Menu,Tags)
  1802.                                A0   A1     A2
  1803.  
  1804.         VOID LT_MenuControlTagList(struct Window *,struct Menu *,struct TagItem *);
  1805.  
  1806.         VOID LT_MenuControlTags(struct Window *,struct Menu *,...);
  1807.  
  1808.    FUNCTION
  1809.  
  1810.         This routine provides a rather efficient way to set and to clear,
  1811.         to enable and to disable a number of menus, menu/submenu items
  1812.         all at once. It is recommended that you disconnect the menu from
  1813.         the windows it is attached to before you call this routine.
  1814.  
  1815.    INPUTS
  1816.  
  1817.         Window - Pointer to Window this menu is attached to. Starting with
  1818.                  gtlayout.library v16 this parameter may be NULL.
  1819.  
  1820.         Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1821.  
  1822.         Tags - Pointer to a list of tagitem values, as found
  1823.                in gtlayout.h
  1824.  
  1825.    TAGS
  1826.  
  1827.         LAMN_ID (ULONG) - Unique ID of menu/menu item/submenu item to
  1828.             manipulate.
  1829.  
  1830.         LAMN_Checked (BOOL) - Set the checkmark state of the
  1831.             menu/submenu item.
  1832.  
  1833.         LAMN_Disabled (BOOL) - Set the availability state of the
  1834.             menu/menu item/submenu item.
  1835.  
  1836.    EXAMPLE
  1837.  
  1838.         The following tagitem list will clear the checkmark and
  1839.         disable the menu item associated with ID 5 and set the
  1840.         checkmark for the item associated with ID 6:
  1841.  
  1842.             LAMN_ID,         5,
  1843.               LAMN_Checked,  FALSE,
  1844.               LAMN_Disabled, TRUE,
  1845.             LAMN_ID,         6,
  1846.               LAMN_Checked,  TRUE,
  1847.             TAG_DONE
  1848.  
  1849.    RESULT
  1850.  
  1851.         none
  1852.  
  1853.    SEE ALSO
  1854.  
  1855.         gtlayout.library/LT_NewMenuTagList
  1856. gtlayout.library/LT_NewA                              gtlayout.library/LT_NewA
  1857.  
  1858.    NAME
  1859.  
  1860.         LT_NewA -- Add a new object to the user interface tree.
  1861.  
  1862.    SYNOPSIS
  1863.  
  1864.         LT_NewA(Handle,Tags);
  1865.                  A0    A1
  1866.  
  1867.         VOID LT_NewA(LayoutHandle *,struct TagItem *);
  1868.  
  1869.         LT_New(Handle,...);
  1870.  
  1871.         VOID LT_New(LayoutHandle *,...);
  1872.  
  1873.    FUNCTION
  1874.  
  1875.         LT_NewA() is the routine you use to build the user interface,
  1876.         you give layout directions, design groups, etc. and finally
  1877.         call LT_BuildA() to turn these specifications into a window.
  1878.  
  1879.    INPUTS
  1880.  
  1881.         Handle - Pointer to LayoutHandle structure.
  1882.  
  1883.    TAGS
  1884.  
  1885.         This routine will accept almost all create-time tag items
  1886.         gadtools.library/CreateGadget will handle. In addition to
  1887.         this there are a bunch of extra gadget objects and extra
  1888.         tag items supported:
  1889.  
  1890.         All object types:
  1891.  
  1892.             LA_Type (LONG) - Type of the object to create, must be
  1893.                              one of the following:
  1894.  
  1895.                                  TEXT_KIND
  1896.                                  VERTICAL_KIND
  1897.                                  HORIZONTAL_KIND
  1898.                                  END_KIND
  1899.                                  FRAME_KIND
  1900.                                  BOX_KIND
  1901.                                  SLIDER_KIND
  1902.                                  LISTVIEW_KIND
  1903.                                  INTEGER_KIND
  1904.                                  STRING_KIND
  1905.                                  PASSWORD_KIND
  1906.                                  PALETTE_KIND
  1907.                                  BUTTON_KIND
  1908.                                  CHECKBOX_KIND
  1909.                                  NUMBER_KIND
  1910.                                  GAUGE_KIND
  1911.                                  CYCLE_KIND
  1912.                                  MX_KIND
  1913.                                  XBAR_KIND
  1914.                                  YBAR_KIND
  1915.                                  FRACTION_KIND
  1916.                                  TAPEDECK_KIND
  1917.                                  LEVEL_KIND
  1918.                                  BOOPSI_KIND
  1919.  
  1920.             LA_LabelText (STRPTR) - The object label text to use.
  1921.  
  1922.             LA_LabelID (LONG) - The locale text ID of the string to
  1923.                                 use as the object label text.
  1924.  
  1925.                                 NOTE: LT_NewA() will fail if you forget
  1926.                                       to select a hook with LH_LocaleHook
  1927.                                       at LT_CreateHandleTagList.
  1928.  
  1929.             LA_ID (LONG) - The gadget ID to use for this object.
  1930.  
  1931.                            NOTE: User ID values *MUST* be greater than 0,
  1932.                                  negative values are reserved for internal
  1933.                                  use.
  1934.  
  1935.             LA_Chars (LONG) - The width of this object measured in
  1936.                 characters. If each character of the user interface
  1937.                 font is 8 pixels wide an object with LA_Chars set to
  1938.                 10 will usually be 80 pixels wide.
  1939.  
  1940.             LA_LabelChars (LONG) - This forces the internal gadget
  1941.                 label width the layout engine calculates during the
  1942.                 layout pass to a specific value. Note: this does
  1943.                 not work well with all objects.
  1944.  
  1945.                 (requires gtlayout.library v9 or higher)
  1946.  
  1947.             LA_LabelPlace (LONG) - Where to place the gadget label.
  1948.                 Not all objects will support all label positions:
  1949.  
  1950.                     PLACE_LEFT - Place label text left of object
  1951.                     PLACE_RIGHT - Place label text right of object
  1952.                     PLACE_ABOVE - Place label text above object
  1953.                     PLACE_IN - Place label text in object
  1954.                     PLACE_BELOW - Place label text below object
  1955.  
  1956.             LA_ExtraSpace (BOOL) - Add extra vertical/horizontal
  1957.                 space before this object.
  1958.                 Default: FALSE
  1959.  
  1960.             LA_ExtraFat (BOOL) - Make this object a bit larger
  1961.                 than its usual size.
  1962.                 Default: FALSE
  1963.  
  1964.             LA_NoKey (BOOL) - Don't let the user interface choose
  1965.                 a keyboard shortcut for this object.
  1966.                 Default: FALSE
  1967.  
  1968.             LA_HighLabel (BOOL) - Use highlight pen when rendering
  1969.                 the gadget label text.
  1970.                 Default: FALSE
  1971.  
  1972.             LA_BYTE (BYTE *) - Pointer to the variable that holds
  1973.                 the "current value" of the object. The layout engine
  1974.                 will retrieve this value initially during the creation
  1975.                 of the object and maintain it during its lifespan.
  1976.                 This means you do not need to worry about checking
  1977.                 the state of the object, the user interface layout
  1978.                 engine will do it for you.
  1979.  
  1980.             LA_UBYTE (UBYTE *) - Pointer to the variable that holds
  1981.                 the "current value" of the object. The layout engine
  1982.                 will retrieve this value initially during the creation
  1983.                 of the object and maintain it during its lifespan.
  1984.                 This means you do not need to worry about checking
  1985.                 the state of the object, the user interface layout
  1986.                 engine will do it for you.
  1987.  
  1988.             LA_WORD (WORD *) - Pointer to the variable that holds
  1989.                 the "current value" of the object. The layout engine
  1990.                 will retrieve this value initially during the creation
  1991.                 of the object and maintain it during its lifespan.
  1992.                 This means you do not need to worry about checking
  1993.                 the state of the object, the user interface layout
  1994.                 engine will do it for you.
  1995.  
  1996.             LA_UWORD (UWORD *) - Pointer to the variable that holds
  1997.                 the "current value" of the object. The layout engine
  1998.                 will retrieve this value initially during the creation
  1999.                 of the object and maintain it during its lifespan.
  2000.                 This means you do not need to worry about checking
  2001.                 the state of the object, the user interface layout
  2002.                 engine will do it for you.
  2003.  
  2004.             LA_BOOL (BOOL *) - Pointer to the variable that holds
  2005.                 the "current value" of the object. The layout engine
  2006.                 will retrieve this value initially during the creation
  2007.                 of the object and maintain it during its lifespan.
  2008.                 This means you do not need to worry about checking
  2009.                 the state of the object, the user interface layout
  2010.                 engine will do it for you.
  2011.  
  2012.             LA_LONG (LONG *) - Pointer to the variable that holds
  2013.                 the "current value" of the object. The layout engine
  2014.                 will retrieve this value initially during the creation
  2015.                 of the object and maintain it during its lifespan.
  2016.                 This means you do not need to worry about checking
  2017.                 the state of the object, the user interface layout
  2018.                 engine will do it for you.
  2019.  
  2020.             LA_ULONG (ULONG *) - Pointer to the variable that holds
  2021.                 the "current value" of the object. The layout engine
  2022.                 will retrieve this value initially during the creation
  2023.                 of the object and maintain it during its lifespan.
  2024.                 This means you do not need to worry about checking
  2025.                 the state of the object, the user interface layout
  2026.                 engine will do it for you.
  2027.  
  2028.             LA_STRPTR (STRPTR) - Pointer to the variable that holds
  2029.                 the "current value" of the object. The layout engine
  2030.                 will retrieve this value initially during the creation
  2031.                 of the object and maintain it during its lifespan.
  2032.                 This means you do not need to worry about checking
  2033.                 the state of the object, the user interface layout
  2034.                 engine will do it for you.
  2035.  
  2036.             LA_FRACTION (FRACTION *) - Pointer to the variable that holds
  2037.                 the "current value" of the object. The layout engine
  2038.                 will retrieve this value initially during the creation
  2039.                 of the object and maintain it during its lifespan.
  2040.                 This means you do not need to worry about checking
  2041.                 the state of the object, the user interface layout
  2042.                 engine will do it for you.
  2043.  
  2044.             TEXT_KIND:
  2045.  
  2046.                 LATX_Picker (BOOL) - Attach a `select' button to the
  2047.                     right hand side of the text display.
  2048.                     Default: FALSE
  2049.  
  2050.                 LATX_LockSize (BOOL) - After doing the initial layout
  2051.                     for this object, do not adapt its size again during
  2052.                     subsequent layouts. This is particularly useful if
  2053.                     you have a TEXT_KIND object in a paged group
  2054.                     and update its contents later. You need
  2055.                     to specify an object width using LA_Chars, otherwise
  2056.                     the layout engine may make it not wide enough to
  2057.                     display any text.
  2058.                     (requires gtlayout.library v15 or higher)
  2059.  
  2060.  
  2061.             VERTICAL_KIND (group to align objects vertically):
  2062.             HORIZONTAL_KIND (group to align objects horizontally):
  2063.  
  2064.                 LAGR_Spread (BOOL) - Place all objects in this
  2065.                     group with roughly the same amount of space
  2066.                     between them.
  2067.                     Default: FALSE
  2068.  
  2069.                 LAGR_SameSize (BOOL) - Make all objects in this
  2070.                     group the same size (for vertical groups:
  2071.                     the same height, for horizontal groups:
  2072.                     the same width).
  2073.                     Default: FALSE
  2074.  
  2075.                 LAGR_LastAttributes (BOOL) - Try to copy the
  2076.                     size of the previous group for this new
  2077.                     group. May not work if this group turns
  2078.                     out to be larger than the previous group.
  2079.                     Default: FALSE
  2080.  
  2081.                 LAGR_ActivePage (LONG) - Organize all child
  2082.                     groups as pages which can be flipped through
  2083.                     using LT_SetAttributes(). You need to
  2084.                     specify the number of the first page to
  2085.                     display, starting from 0.
  2086.  
  2087.                     NOTE: Specifying this tag actually enables
  2088.                           the paging feature. If you omit this
  2089.                           tag calls to flip to a specific
  2090.                           page will fail.
  2091.  
  2092.                     Default: No paging
  2093.  
  2094.                 LAGR_Frame (BOOL) - Draw a recessed frame around
  2095.                     this group, even if there is no group label.
  2096.                     (requires gtlayout.library v7 or higher)
  2097.  
  2098.                 LAGR_IndentX (BOOL) - Add extra horizontal indentation
  2099.                     for this group.
  2100.                     (requires gtlayout.library v10 or higher)
  2101.  
  2102.                 LAGR_IndentY (BOOL) - Add extra vertical indentation
  2103.                     for this group.
  2104.                     (requires gtlayout.library v10 or higher)
  2105.  
  2106.  
  2107.             FRAME_KIND (fixed size general purpose display,
  2108.                 you may render into it):
  2109.  
  2110.                 LAFR_InnerWidth (LONG) - Inner width of the
  2111.                     display box.
  2112.  
  2113.                 LAFR_InnerHeight (LONG) - Inner height of the
  2114.                     display box.
  2115.  
  2116.                 LAFR_DrawBox (BOOL) - Draw a recessed bevel box
  2117.                     around the display box.
  2118.                     Default: FALSE
  2119.  
  2120.                 LAFR_RefreshHook (struct Hook *) - Hook to call
  2121.                     when refreshing/redrawing this object. See
  2122.                     gtlayout.h for more information.
  2123.                     (requires gtlayout.library v9 or higher)
  2124.  
  2125.  
  2126.             XBAR_KIND (horizontal separator bar):
  2127.  
  2128.                 LAXB_FullSize (BOOL) - Make this separator bar span
  2129.                     the entire window width.
  2130.  
  2131.  
  2132.             BOX_KIND (multiline text display):
  2133.  
  2134.                 LABX_Labels (STRPTR *) - The label texts to display
  2135.                     on the right hand side of the box. Terminate
  2136.                     this array with NULL.
  2137.  
  2138.                 LABX_Lines (STRPTR *) - The text to display in the
  2139.                     box. Terminate this array with NULL.
  2140.  
  2141.                 LABX_Rows (LONG) - The width of this object in
  2142.                     characters. The layout routine will try to make
  2143.                     sure that the given number of characters will
  2144.                     fit into a single line of text in this box.
  2145.                     This may be a problem with proportional spaced
  2146.                     fonts.
  2147.  
  2148.                 LABX_AlignText (LONG) - Controls how text is aligned
  2149.                     in box lines:
  2150.  
  2151.                         ALIGNTEXT_LEFT - Align text to the left edge
  2152.                         ALIGNTEXT_CENTERED - Centre the text
  2153.                         ALIGNTEXT_RIGHT - Align text to the right edge
  2154.                         ALIGNTEXT_PAD - Pad text lines
  2155.  
  2156.                     Default: ALIGNTEXT_LEFT
  2157.  
  2158.                 LABX_DrawBox (BOOL) - Draw a recessed bevel box
  2159.                     around the text box.
  2160.                     Default: FALSE
  2161.  
  2162.                 LABX_FirstLabel (LONG) - Locale string ID of the first
  2163.                     text to use as a box label. Works in conjunction
  2164.                     with LABX_LastLabel.
  2165.  
  2166.                 LABX_LastLabel (LONG) - Locale string ID of the last
  2167.                     text to use as a box label. Works in conjunction
  2168.                     with LABX_FirstLabel. When building the interface the
  2169.                     code will loop from FirstLabel..LastLabel, look
  2170.                     up the corresponding locale strings and use the
  2171.                     data to make up the label text to appear at the
  2172.                     right hand side of the box.
  2173.  
  2174.                 LABX_LabelTable (LONG *) - Pointer to an array of IDs
  2175.                     to use for building the box labels. This requires
  2176.                     that a locale hook is provided with the layout handle.
  2177.                     The array is terminated by -1.
  2178.  
  2179.                 LABX_ReserveSpace (BOOL) - Allocate extra memory to hold
  2180.                     the contents of the lines displayed. This avoids nasty
  2181.                     side-effects when refreshing this object.
  2182.                     Default: FALSE
  2183.  
  2184.             FRACTION_KIND:
  2185.  
  2186.                 LAFC_MaxChars (LONG) - Maximum number of characters to
  2187.                     fit into the entry field.
  2188.                     Default: 16
  2189.  
  2190.                 LAFC_Number (FIXED) - Fixed point number to use for
  2191.                     this object.
  2192.                     Default: 0.0
  2193.  
  2194.                 LAFC_LastGadget (BOOL) - When cycling through the
  2195.                     text entry fields, stop cycling after leaving
  2196.                     this object.
  2197.                     Default: FALSE
  2198.  
  2199.                 LAFC_Min (FIXED) - Minimum value allowed for this
  2200.                     object.
  2201.  
  2202.                 LAFC_Max (FIXED) - Maximum value allowed for this
  2203.                     object.
  2204.  
  2205.                 LAFC_HistoryLines (LONG) - Maximum number of entries
  2206.                     to keep as a backlog.
  2207.                     Default: 0
  2208.  
  2209.                 LAFC_HistoryHook (struct Hook *) - Hook code to call
  2210.                     when entering a number into the backlog. See
  2211.                     gtlayout.h for more information.
  2212.                     Default: NULL
  2213.  
  2214.             SLIDER_KIND:
  2215.  
  2216.                 LASL_FullCheck: TRUE will cause the code to rattle
  2217.                     through all possible slider settings, starting
  2218.                     from the minimum value, ending at the maximum value.
  2219.                     While this may be a good idea for a display
  2220.                     function to map slider levels to text strings
  2221.                     of varying length it might be a problem when
  2222.                     it comes to display a range of numbers from
  2223.                     1 to 40,000: the code will loop through
  2224.                     40,000 iterations trying to find the longest
  2225.                     string.
  2226.  
  2227.                     FALSE will cause the code to calculate the
  2228.                     longest level string based only on the
  2229.                     minimum and the maximum value to check.
  2230.                     While this is certainly a good a idea when
  2231.                     it comes to display a range of numbers from
  2232.                     1 to 40,000 as only two values will be
  2233.                     checked the code may fail to produce
  2234.                     accurate results for sliders using display
  2235.                     functions mapping slider levels to strings.
  2236.  
  2237.                     Default: TRUE
  2238.  
  2239.             LEVEL_KIND:
  2240.  
  2241.                 All tags are supported which SLIDER_KIND supports.
  2242.                 The gadget level display however, can only be aligned
  2243.                 to the left border.
  2244.  
  2245.             LISTVIEW_KIND:
  2246.  
  2247.                 LALV_ExtraLabels (STRPTR *) - Place extra line
  2248.                     labels at the right of the box. Terminate
  2249.                     this array with NULL.
  2250.  
  2251.                 LALV_Labels (STRPTR *) - The labels to display
  2252.                     inside the box, you can pass this array of
  2253.                     strings in rather than passing an initialized
  2254.                     List of text via GTLV_Labels. Terminate
  2255.                     this array with NULL.
  2256.  
  2257.                 LALV_CursorKey (BOOL) - Let the user operate this
  2258.                     listview using the cursor keys.
  2259.  
  2260.                     NOTE: there can be only one single listview
  2261.                           per window to sport this feature.
  2262.  
  2263.                     Default: FALSE
  2264.  
  2265.                 LALV_Lines (LONG) - The number of text lines this
  2266.                     listview is to display.
  2267.  
  2268.                 LALV_Link (LONG) - The Gadget ID of a string gadget
  2269.                     to attach to this listview. NOTE: you need to
  2270.                     add the Gadget in question before you add the
  2271.                     listview to refer to it or the layout routine
  2272.                     will get confused.
  2273.                     Passing the value NIL_LINK will create a listview
  2274.                     which displays the currently selected item, otherwise
  2275.                     you will get a read-only list.
  2276.  
  2277.                 LALV_FirstLabel (LONG) - Locale string ID of the first
  2278.                     text to use as a list label. Works in conjunction
  2279.                     with LALV_LastLabel.
  2280.  
  2281.                 LALV_LastLabel (LONG) - Locale string ID of the last
  2282.                     text to use as a list label. Works in conjunction
  2283.                     with LALV_FirstLabel. When building the interface the
  2284.                     code will loop from FirstLabel..LastLabel, look
  2285.                     up the corresponding locale strings and use the
  2286.                     data to make up the label text to appear in the
  2287.                     list.
  2288.  
  2289.                 LALV_LabelTable (LONG *) - Pointer to an array of IDs
  2290.                     to use for building the listview contents. This requires
  2291.                     that a locale hook is provided with the layout handle.
  2292.                     The array is terminated by -1.
  2293.  
  2294.                 LALV_MaxGrowX (LONG) - Maximum width of this object
  2295.                     measured in characters. When the first layout pass
  2296.                     is finished and there is still enough space left
  2297.                     to make the listview wider, the width is increased
  2298.                     until it hits the limit specified using this tag.
  2299.  
  2300.                     NOTE: there can be only one single listview
  2301.                           per window to sport this feature.
  2302.  
  2303.                     Default: 0
  2304.  
  2305.                 LALV_MaxGrowY (LONG) - Maximum height of this object
  2306.                     measured in lines. When the first layout pass is
  2307.                     finished and there is till enough space left to
  2308.                     make the listview higher, the height is increased
  2309.                     until it hits the limit specified using this tag.
  2310.  
  2311.                     NOTE: there can be only one single listview
  2312.                           per window to sport this feature.
  2313.  
  2314.                     Default: 0
  2315.  
  2316.                 LALV_ResizeX (BOOL) - Makes this listview resizable
  2317.                     in the horizontal direction, attaches a sizing
  2318.                     gadget to the window to open and handles window
  2319.                     resize operations automatically.
  2320.                     (requires gtlayout.library v9 or higher)
  2321.  
  2322.                     NOTE: there can be only one single listview
  2323.                           per window to sport this feature.
  2324.  
  2325.                           Also listen to IDCMP_CLOSEWINDOW events
  2326.                           which may be generated if the layout
  2327.                           engine runs out of memory when rebuilding
  2328.                           the user interface.
  2329.  
  2330.                     Default: FALSE
  2331.  
  2332.                 LALV_ResizeY (BOOL) - Makes this listview resizable
  2333.                     in the vertical direction, attaches a sizing
  2334.                     gadget to the window to open and handles window
  2335.                     resize operations automatically.
  2336.                     (requires gtlayout.library v9 or higher)
  2337.  
  2338.                     NOTE: there can be only one single listview
  2339.                           per window to sport this feature.
  2340.  
  2341.                           Also listen to IDCMP_CLOSEWINDOW events
  2342.                           which may be generated if the layout
  2343.                           engine runs out of memory when rebuilding
  2344.                           the user interface.
  2345.  
  2346.                     Default: FALSE
  2347.  
  2348.                 LALV_MinChars (WORD) - Minimum width for this
  2349.                     object, measured in characters. Used in
  2350.                     conjunction with LALV_ResizeX.
  2351.                     (requires gtlayout.library v9 or higher)
  2352.  
  2353.                 LALV_MinLines (WORD) - Minimum height for this
  2354.                     object, measured in lines. Used in
  2355.                     conjunction with LALV_ResizeY.
  2356.                     (requires gtlayout.library v9 or higher)
  2357.  
  2358.                 LALV_LockSize (BOOL) - After doing the initial layout
  2359.                     for this object, do not adapt its size again during
  2360.                     subsequent layouts. This is particularly useful if
  2361.                     you have a LISTVIEW_KIND object in a paged group
  2362.                     and keep adding new entries to the list. You need
  2363.                     to specify an object width using LA_Chars, otherwise
  2364.                     the layout engine may make it not wide enough to
  2365.                     display any entries.
  2366.                     (requires gtlayout.library v8 or higher)
  2367.  
  2368.                 LALV_FlushLabelLeft (BOOL) - For a gadget label placed
  2369.                     above the listview align the text to the left edge
  2370.                     of the view.
  2371.                     (requires gtlayout.library v9 or higher)
  2372.  
  2373.                 LALV_TextAttr (struct TextAttr *) - You can specify a
  2374.                     fixed-width font to be used for the list display.
  2375.                     The TextAttr (or TTextAttr) you provide must be ready
  2376.                     to go so the layout code can open the font later.
  2377.  
  2378.                     To get the current system default font, which is
  2379.                     guaranteed to be fixed-width, pass ~0 instead of a
  2380.                     pointer to a TextAttr structure.
  2381.  
  2382.                     NOTE: The font *MUST* be fixed-width or the layout
  2383.                           will fail.
  2384.  
  2385.                           Choose your font in such a way that it matches
  2386.                           in width and height with the other probably
  2387.                           proportional-spaced user interface font.
  2388.  
  2389.                           If the layout engine decides to step down in
  2390.                           font size, all LISTVIEW_KIND objects which were
  2391.                           configured to use a special fixed-width font
  2392.                           will `forget' about it. This won't matter much
  2393.                           as the fonts the engine chooses will always be
  2394.                           fixed-width anyway.
  2395.  
  2396.                     (requires gtlayout.library v10 or higher)
  2397.  
  2398.             INTEGER_KIND:
  2399.  
  2400.                 LAIN_LastGadget (BOOL) - Pressing return with this
  2401.                     gadget active will stop activating the next
  2402.                     following string gadget type if TRUE is passed.
  2403.                     Default: FALSE
  2404.  
  2405.                 LAIN_Min (LONG) - Minimum accepted numeric value.
  2406.                     Default: -2147483647
  2407.  
  2408.                 LAIN_Max (LONG) - Maximum accepted numeric value.
  2409.                     Default:  2147483647
  2410.  
  2411.                 LAIN_UseIncrementers (BOOL) - Use TRUE to add incrementer
  2412.                     arrow buttons to the right of the numeric entry field.
  2413.                     These buttons will let you cycle through a set of
  2414.                     numbers to be displayed in the numeric entry field.
  2415.                     Default: FALSE
  2416.  
  2417.                 LAIN_HistoryLines (LONG) - Number of numbers entered to
  2418.                     keep as a backlog.
  2419.                     Default: 0
  2420.  
  2421.                 LAIN_HistoryHook (struct Hook *) - Hook code to call when
  2422.                     entering a number into the backlog. See gtlayout.h for
  2423.                     more information.
  2424.                     Default: NULL
  2425.  
  2426.                 LAIN_IncrementerHook (struct Hook *) - Hook code to call
  2427.                     when cycling through numeric values. See gtlayout.h for
  2428.                     more information.
  2429.                     Default: NULL
  2430.  
  2431.  
  2432.             STRING_KIND:
  2433.  
  2434.                 LAST_LastGadget (BOOL) - Pressing return with this
  2435.                     gadget active will stop activating the next
  2436.                     following string gadget type if TRUE is passed.
  2437.                     Default: FALSE
  2438.  
  2439.                 LAST_Link (LONG) - Gadget ID of the listview to attach
  2440.                     this string gadget to. NOTE: you need to
  2441.                     add the string gadget before you add the
  2442.                     listview to refer to it or the layout routine
  2443.                     will get confused.
  2444.  
  2445.                 LAST_Picker (BOOL) - Attach a `select' button to the
  2446.                     right hand side of the string gadget.
  2447.                     Default: FALSE
  2448.  
  2449.                 LAST_HistoryLines (LONG) - Number of lines to keep as
  2450.                     a backlog.
  2451.                     Default: 0
  2452.  
  2453.                 LAST_HistoryHook (struct Hook *) - Hook code to call
  2454.                     when entering a line into the backlog. See gtlayout.h
  2455.                     for more information.
  2456.                     Default: NULL
  2457.  
  2458.  
  2459.             PASSWORD_KIND (string gadget type which does not
  2460.                 display its contents):
  2461.  
  2462.                 LAPW_LastGadget (BOOL) - Pressing return with this
  2463.                     gadget active will stop activating the next
  2464.                     following string gadget type if TRUE is passed.
  2465.                     Default: FALSE
  2466.  
  2467.                 LAPW_HistoryLines (LONG) - Number of lines to keep as
  2468.                     a backlog.
  2469.                     Default: 0
  2470.  
  2471.                 LAPW_HistoryHook (struct Hook *) - Hook code to call
  2472.                     when entering a line into the backlog. See gtlayout.h
  2473.                     for more information.
  2474.                     Default: NULL
  2475.  
  2476.                 This object type accepts all the GTST_#? tag items.
  2477.  
  2478.  
  2479.             PALETTE_KIND:
  2480.  
  2481.                 LAPA_SmallPalette (BOOL) - Make the palette display
  2482.                     a bit smaller than usual.
  2483.                     Default: FALSE
  2484.  
  2485.                 LAPA_Lines (LONG) - Number of lines the palette
  2486.                     display should cover.
  2487.                     Default: No preference
  2488.  
  2489.                 LAPA_UsePicker (BOOL) - This tag effectively changes the
  2490.                     gadget type. Instead of a list of colours to pick from
  2491.                     the user will see a rectangle filled in the selected
  2492.                     colour with a picker button next to it. This gadget
  2493.                     will generate IDCMP_IDCMPUPDATE events when the picker
  2494.                     button is pressed.
  2495.                     (requires gtlayout.library v10 or higher)
  2496.  
  2497.             BUTTON_KIND:
  2498.  
  2499.                 LA_Label (STRPTR)
  2500.                 LA_LabelID (LONG) - These two define the button label, i.e.
  2501.                     the text that is printed within the button box. Optionally,
  2502.                     this text may include newline characters ("\n") which will
  2503.                     cause the button text to be broken into several lines.
  2504.                     This particular feature requires gtlayout.library v12 or
  2505.                     higher. Single line label have always been supported.
  2506.  
  2507.                 LABT_ReturnKey (BOOL) - Let the user operate this
  2508.                     button by pressing the return key. There will
  2509.                     be a recessed bevel box drawn around the button
  2510.                     to indicate this special feature.
  2511.  
  2512.                     NOTE: there can be only one single button per
  2513.                     window to sport this feature.
  2514.  
  2515.                     Default: FALSE
  2516.  
  2517.                 LABT_EscKey (BOOL) - Let the user operate this
  2518.                     button by pressing the Escape key.
  2519.  
  2520.                     NOTE: there can be only one single button per
  2521.                     window to use this feature.
  2522.  
  2523.                     Default: FALSE
  2524.  
  2525.                 LABT_ExtraFat (BOOL) - Make this button a bit
  2526.                     larger than usual.
  2527.                     Default: FALSE
  2528.  
  2529.                 LABT_Lines (STRPTR *) - Use the given string array
  2530.                     to create a multiline gadget label. Terminate the
  2531.                     array with a NULL.
  2532.                     (requires gtlayout.library v12 or higher)
  2533.  
  2534.                 LABT_FirstLine (LONG) - Locale ID of first label line.
  2535.                     (requires gtlayout.library v12 or higher)
  2536.  
  2537.                 LABT_LastLine (LONG) - Locale ID of last label line.
  2538.                     (requires gtlayout.library v12 or higher)
  2539.  
  2540.             GAUGE_KIND (general purpose progress report display):
  2541.  
  2542.                 LAGA_Percent (LONG) - Indicator position, can range
  2543.                     from 0..100.
  2544.                     Default: 0
  2545.  
  2546.                 LAGA_InfoLength (LONG) - Maximum number of characters
  2547.                     to reserve for text printed in the gauge display.
  2548.                     Default: 0
  2549.  
  2550.                 LAGA_InfoText (STRPTR) - Text to print in the gauge
  2551.                     display.
  2552.  
  2553.  
  2554.             CYCLE_KIND:
  2555.  
  2556.                 LACY_FirstLabel (LONG) - Locale string ID of the first
  2557.                     text to use as a label. Works in conjunction
  2558.                     with LACY_LastLabel.
  2559.  
  2560.                 LACY_LastLabel (LONG) - Locale string ID of the last
  2561.                     text to use as a label. Works in conjunction
  2562.                     with LACY_FirstLabel. When building the interface the
  2563.                     code will loop from FirstLabel..LastLabel, look
  2564.                     up the corresponding locale strings and use the
  2565.                     data to make up the label text.
  2566.  
  2567.                 LACY_LabelTable (LONG *) - Pointer to an array of IDs
  2568.                     to use for building the cycle labels. This requires
  2569.                     that a locale hook is provided with the layout handle.
  2570.                     The array is terminated by -1.
  2571.  
  2572.                 LACY_TabKey (BOOL) - Connect this object to the tabulator
  2573.                     key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2574.                     to cycle to the previous entry.
  2575.  
  2576.                     NOTE: there can be only one single button per
  2577.                     window to use this feature.
  2578.  
  2579.                     Default: FALSE
  2580.                     (requires gtlayout.library v9 or higher)
  2581.  
  2582.                 LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2583.                     which will be set to the gadget's current setting.
  2584.                     (requires gtlayout.library v7 or higher)
  2585.  
  2586.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2587.                           which may be generated if the layout
  2588.                           engine runs out of memory when rebuilding
  2589.                           the user interface.
  2590.  
  2591.             MX_KIND:
  2592.  
  2593.                 LAMX_FirstLabel (LONG) - Locale string ID of the first
  2594.                     text to use as a label. Works in conjunction
  2595.                     with LAMX_LastLabel.
  2596.  
  2597.                 LAMX_LastLabel (LONG) - Locale string ID of the last
  2598.                     text to use as a label. Works in conjunction
  2599.                     with LAMX_FirstLabel. When building the interface the
  2600.                     code will loop from FirstLabel..LastLabel, look
  2601.                     up the corresponding locale strings and use the
  2602.                     data to make up the label text.
  2603.  
  2604.                 LAMX_LabelTable (LONG *) - Pointer to an array of IDs
  2605.                     to use for building the radio labels. This requires
  2606.                     that a locale hook is provided with the layout handle.
  2607.                     The array is terminated by -1.
  2608.  
  2609.                 LAMX_TabKey (BOOL) - Connect this object to the tabulator
  2610.                     key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2611.                     to cycle to the previous entry.
  2612.  
  2613.                     NOTE: there can be only one single button per
  2614.                     window to use this feature.
  2615.  
  2616.                     Default: FALSE
  2617.                     (requires gtlayout.library v9 or higher)
  2618.  
  2619.                 LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2620.                     which will be set to the gadget's current setting.
  2621.                     (requires gtlayout.library v7 or higher)
  2622.  
  2623.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2624.                           which may be generated if the layout
  2625.                           engine runs out of memory when rebuilding
  2626.                           the user interface.
  2627.  
  2628.             SCROLLER_KIND:
  2629.  
  2630.                 LASC_Thin (BOOL) - Make the scroller a bit thinner
  2631.                     than usual.
  2632.                     Default: FALSE
  2633.  
  2634.             TAPEDECK_KIND:
  2635.  
  2636.                 LATD_ButtonType (LONG) - Select the image to display
  2637.                     in the button, must be one of the following:
  2638.  
  2639.                         DTBT_BACKWARD
  2640.                             "<<" Symbol
  2641.  
  2642.                         DTBT_FORWARD
  2643.                             ">>" Symbol
  2644.  
  2645.                         DTBT_PREVIOUS
  2646.                             "|<" Symbol
  2647.  
  2648.                         DTBT_NEXT
  2649.                             ">|" Symbol
  2650.  
  2651.                         DTBT_STOP
  2652.                             Stop symbol (filled square)
  2653.  
  2654.                         DTBT_PAUSE
  2655.                             Pause symbol (broken square)
  2656.  
  2657.                         DTBT_RECORD
  2658.                             Record symbol (filled circle)
  2659.  
  2660.                         DTBT_REWIND
  2661.                             "<" symbol
  2662.  
  2663.                         DTBT_EJECT
  2664.                             Eject symbol (broken upward pointing arrow)
  2665.  
  2666.                         DTBT_PLAY
  2667.                             ">" symbol
  2668.  
  2669.                 LATD_Toggle (BOOL) - Make this object a toggle-select
  2670.                     button.
  2671.                     Default: FALSE
  2672.  
  2673.                 LATD_Pressed (BOOL) - Make this button appear to be
  2674.                     pressed.
  2675.  
  2676.                     NOTE: requires "LATD_Toggle,TRUE" attribute.
  2677.  
  2678.                     Default: FALSE
  2679.  
  2680.                 LATD_Smaller (BOOL) - Make this button a bit smaller
  2681.                     than usual.
  2682.                     Default: FALSE
  2683.  
  2684.                 LATD_Tick (BOOL) - Hear IDCMP_GADGETUP events while the
  2685.                     buttons is being pressed; the IntuiMessage->Code entry
  2686.                     will be 0 while the button is being pressed, and
  2687.                     will be 1 as soon as the button is released.
  2688.  
  2689.                     Default: FALSE
  2690.  
  2691.                     (requires gtlayout.library v12 or higher)
  2692.  
  2693.             BOOPSI_KIND:
  2694.  
  2695.                 (requires gtlayout.library v10 or higher)
  2696.  
  2697.                 LABO_TagCurrent (Tag) - The Tag ID that represents the
  2698.                     current object value. For PROPGCLASS this would be
  2699.                     PGA_Top.
  2700.  
  2701.                 LABO_TagTextAttr (Tag) - The Tag ID that represents the
  2702.                     TextAttr value the object expects. For gadgets this
  2703.                     would be GA_TextAttr.
  2704.  
  2705.                 LABO_TagDrawInfo (Tag) - The Tag ID that represents the
  2706.                     DrawInfo value the object expects.
  2707.  
  2708.                 LABO_TagLink (Tag) - The Tag ID that represents a pointer
  2709.                     to a different object the object expects. For the
  2710.                     colorwheel.gadget this would be WHEEL_GradientSlider.
  2711.  
  2712.                 LABO_TagScreen (Tag) - The Tag ID that represents the
  2713.                     screen the object expects. For the colorwheel.gadget
  2714.                     this would be WHEEL_Screen.
  2715.  
  2716.                 LABO_Link (LONG) - The ID of the object this object should
  2717.                     be linked to. This will be resolved later when gadgets
  2718.                     are created.
  2719.  
  2720.                     NOTE: Forward references are not resolved, only backward
  2721.                           references are allowed. This means that if you wish
  2722.                           to link object A to object B, object A must be
  2723.                           created before object B is created.
  2724.  
  2725.                 LABO_ClassInstance (Class *) - This is the first parameter you would
  2726.                     pass to NewObjectA().
  2727.  
  2728.                     NOTE: Only classes derived from gadgetclass and gadgetclass itself
  2729.                           may be used.
  2730.  
  2731.                 LABO_ClassName (STRPTR) - This is the second parameter you would
  2732.                     pass to NewObject().
  2733.  
  2734.                     NOTE: Only classes derived from gadgetclass and gadgetclass itself
  2735.                           may be used.
  2736.  
  2737.                 LABO_ClassLibraryName (STRPTR) - This tag is particularly useful
  2738.                     for gadget class implementations wrapped into libraries, such as
  2739.                     colorwheel.gadget. When opened, they make the classes they
  2740.                     represent publicly available so subsequent calls to
  2741.                     NewObject(NULL,<Classname>,...) can be made. The
  2742.                     LABO_ClassLibraryName tag will cause gtlayout.library to open
  2743.                     the class library before any calls to NewObject() are made.
  2744.  
  2745.                     NOTE: Only classes derived from gadgetclass and gadgetclass itself
  2746.                           may be used.
  2747.  
  2748.                           The LABO_ClassLibraryName tag requires that you specify the
  2749.                           class name with the LABO_ClassName. It is not enough to
  2750.                           just use the LABO_ClassLibraryName tag.
  2751.  
  2752.                 LABO_ExactWidth (WORD) - This is the exact width of the object to
  2753.                     use. This effectively overrides whatever you specified using
  2754.                     the LA_Chars tag and keeps gtlayout.library from shrinking and
  2755.                     expanding the object as needed.
  2756.  
  2757.                 LABO_ExactHeight (WORD) - This is the exact height of the object to
  2758.                     use. This effectively overrides whatever you specified using
  2759.                     the LA_Lines tag and keeps gtlayout.library from shrinking and
  2760.                     expanding the object as needed.
  2761.  
  2762.                 LABO_RelFontHeight (WORD) - This tag affects the height of the
  2763.                     object; when specified, it is derived from the user interface
  2764.                     font height plus the value given with LABO_RelFontHeight.
  2765.  
  2766.                 LABO_FullWidth (BOOL) - Use this tag if you wish the object to
  2767.                     cover the entire width of the group it resides within.
  2768.  
  2769.                 LABO_FullHeight (BOOL) - Use this tag if you wish the object to
  2770.                     cover the entire height of the group it resides within.
  2771.  
  2772.                 LABO_ActivateHook (struct Hook *) - Hook to invoke when the
  2773.                     layout engine decides that this particular object should
  2774.                     be activated. The hook is called with the following
  2775.                     parameters:
  2776.  
  2777.                     Success = ActivateFunc(struct Hook *Hook,LayoutHandle *Handle,
  2778.                       D0                                 A0                  A2
  2779.  
  2780.                                  Object *object)
  2781.                                            A1
  2782.  
  2783.                     The object pointer actually refers to the instance of the
  2784.                     BOOPSI object created. Return FALSE if your object could not
  2785.                     be activated, TRUE if it worked. If you return TRUE, no special
  2786.                     keyboard event will be generated.
  2787.  
  2788.                     (requires gtlayout.library v13 or higher)
  2789.  
  2790.                 NOTE: All tags passed to LT_New() for BOOPSI_KIND objects are
  2791.                       passed through to NewObjectA() later. The library makes
  2792.                       a copy of the tag item list, so all data valid in the
  2793.                       scope when LT_New() iss called must also be valid later
  2794.                       when LT_Build() is invoked.
  2795.  
  2796.                       The gadget label is *NOT* passed through to the object,
  2797.                       it effectively receives the label a plain gadtools object
  2798.                       would receive, similar to what happens to FRAME_KIND
  2799.                       objects and the like.
  2800.  
  2801.    RESULT
  2802.  
  2803.         none
  2804. gtlayout.library/LT_NewLevelWidth                  gtlayout.library/LT_NewLevelWidth
  2805.  
  2806.    NAME
  2807.  
  2808.         LT_NewLevelWidth -- Determine the maximum width of a SLIDER_KIND
  2809.                             level string. (V14)
  2810.  
  2811.    SYNOPSIS
  2812.  
  2813.         Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  2814.           D0                    A0        A1         A2     D0  D1    A3
  2815.  
  2816.                                   MaxLen,FullCheck);
  2817.                                     D3      D2
  2818.  
  2819.         LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  2820.                            LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  2821.                            LONG *,BOOL);
  2822.  
  2823.    FUNCTION
  2824.  
  2825.         In order to make room for the level text displayed by a
  2826.         SLIDER_KIND object one needs to know how much space the
  2827.         longest level string will occupy. Otherwise, the level
  2828.         text may overwrite the gadget label text or the slider
  2829.         container. This routine will rattle through all possible
  2830.         slider settings (as given via the Min and the Max
  2831.         level values) and determine the longest label string
  2832.         according to the font used.
  2833.  
  2834.    INPUTS
  2835.  
  2836.         Handle - Pointer to a LayoutHandle structure, as returned by
  2837.                  a call to LT_CreateHandleTags().
  2838.  
  2839.         FormatString - The sprintf() style formatting string to be used
  2840.                        to format the slider level settings into text.
  2841.                        This is the same string you would pass in via
  2842.                        the GTSL_LevelFormat tag when creating the
  2843.                        slider object.
  2844.                        Default: "%lD" for systems which have locale.library
  2845.                                 installed, "%ld" otherwise.
  2846.  
  2847.         DispFunc - A pointer to the function to filter the slider level
  2848.                    values. The result of this function will then be
  2849.                    used to format a string into the slider level text.
  2850.                    This is the same parameter you would pass in via
  2851.                    the GTSL_DispFunc tag when creating the slider
  2852.                    object.
  2853.  
  2854.                    NOTE: the routine will be called with a NULL Gadget
  2855.                          parameter, make sure your code will handle
  2856.                          this nicely.
  2857.  
  2858.                    Default: no display function
  2859.  
  2860.         Min - The smallest value the slider can be set to. This is
  2861.               same value you would pass in via GTSL_Min when creating
  2862.               the slider object.
  2863.  
  2864.         Max - The largest value the slider can be set to. This is
  2865.               same value you would pass in via GTSL_Max when creating
  2866.               the slider object.
  2867.  
  2868.         MaxWidth - Pointer to a place to store the width of the
  2869.                    longest level string in pixels. If you pass
  2870.                    in NULL instead of the address of a variable
  2871.                    no harm will be done.
  2872.  
  2873.         MaxLen - Pointer to a place to store the length of the
  2874.                  longest level string in characters. If you pass
  2875.                  in NULL instead of the address of a variable
  2876.                  no harm will be done.
  2877.  
  2878.  
  2879.         FullCheck - TRUE will cause the code to rattle through all
  2880.                     possible slider settings, starting from the
  2881.                     minimum value, ending at the maximum value.
  2882.                     While this may be a good idea for a display
  2883.                     function to map slider levels to text strings
  2884.                     of varying length it might be a problem when
  2885.                     it comes to display a range of numbers from
  2886.                     1 to 40,000: the code will loop through
  2887.                     40,000 iterations trying to find the longest
  2888.                     string.
  2889.  
  2890.                     FALSE will cause the code to calculate the
  2891.                     longest level string based only on the
  2892.                     minimum and the maximum value to check.
  2893.                     While this is certainly a good a idea when
  2894.                     it comes to display a range of numbers from
  2895.                     1 to 40,000 as only two values will be
  2896.                     checked the code may fail to produce
  2897.                     accurate results for sliders using display
  2898.                     functions mapping slider levels to strings.
  2899.  
  2900.     RESULT
  2901.  
  2902.         Index - The slider level which gives the longest
  2903.                 level string.
  2904.  
  2905.     NOTES
  2906.  
  2907.         This function does exactly what gtlayout.library/LT_LevelWidth
  2908.         does, but uses a slightly different register ordering. Namely,
  2909.         the MaxLen pointer is passed in D3 instead of A5.
  2910. gtlayout.library/LT_NewMenuTagList            gtlayout.library/LT_NewMenuTagList
  2911.  
  2912.    NAME
  2913.  
  2914.         LT_NewMenuTagList -- Allocate and layout menu items (V11)
  2915.  
  2916.    SYNOPSIS
  2917.  
  2918.         Menu = LT_NewMenuTagList(Tags)
  2919.          D0                       A0
  2920.  
  2921.         struct Menu *LT_NewMenuTagList(struct TagItem *);
  2922.  
  2923.         struct Menu *LT_NewMenuTags(...);
  2924.  
  2925.    FUNCTION
  2926.  
  2927.         Allocates Menus and MenuItems similar to LT_LayoutMenus().
  2928.  
  2929.    INPUTS
  2930.  
  2931.         Tags - Pointer to a list of tagitem values, as found
  2932.                in gtlayout.h
  2933.  
  2934.    TAGS
  2935.  
  2936.         LAMN_Screen (struct Screen *) - Pointer to the Screen
  2937.             the menu is to appear upon. This tag is mandatory,
  2938.             unless the LAMN_LayoutHandle tag is used.
  2939.  
  2940.         LAMN_TextAttr (struct TextAttr *) - Pointer to the
  2941.             TextAttr to use for the menu layout. If this tag
  2942.             is omitted the Screen->Font will be used.
  2943.  
  2944.         LAMN_Error (LONG *) - Pointer to variable to receive
  2945.             an error in case of failure.
  2946.  
  2947.         LAMN_AmigaGlyph (struct Image *) - Pointer to Image to
  2948.             use as the Amiga glyph in menus.
  2949.  
  2950.             NOTE: Ignored by intuition.library v37 and below.
  2951.  
  2952.         LAMN_CheckmarkGlyph (struct Image *) - Pointer to Image to
  2953.             use as the checkmark glyph in menus.
  2954.  
  2955.         LAMN_LayoutHandle (LayoutHandle *) - Pointer to a valid
  2956.             LayoutHandle as created by LT_CreateHandle. This tag
  2957.             provides all the information the single tags
  2958.             LAMN_Screen..LAMN_CheckmarkGlyph would otherwise
  2959.             need to provide.
  2960.  
  2961.         LAMN_TitleText (STRPTR) - Name of new menu to create.
  2962.             You may precede the name with the keyboard shortcut
  2963.             to assign to this menu item as follows:
  2964.  
  2965.                A\0Save as...
  2966.  
  2967.             This will create a menu item using the shortcut "A"
  2968.             and the title "Save as...".
  2969.  
  2970.         LAMN_TitleID (LONG) - Locale ID corresponding to the
  2971.             name of the new menu to create.
  2972.             You may precede the name with the keyboard shortcut
  2973.             to assign to this menu item as follows:
  2974.  
  2975.                A\0Save as...
  2976.  
  2977.             This will create a menu item using the shortcut "A"
  2978.             and the title "Save as...".
  2979.  
  2980.         LAMN_ItemText (STRPTR) - Name of new menu item to create.
  2981.             You may precede the name with the keyboard shortcut
  2982.             to assign to this menu item as follows:
  2983.  
  2984.                A\0Save as...
  2985.  
  2986.             This will create a menu item using the shortcut "A"
  2987.             and the title "Save as...".
  2988.  
  2989.         LAMN_ItemID (LONG) - Locale ID corresponding to the
  2990.             name of the new menu item to create.
  2991.             You may precede the name with the keyboard shortcut
  2992.             to assign to this menu item as follows:
  2993.  
  2994.                A\0Save as...
  2995.  
  2996.             This will create a menu item using the shortcut "A"
  2997.             and the title "Save as...".
  2998.  
  2999.         LAMN_SubText (STRPTR) - Name of new submenu item to create.
  3000.             You may precede the name with the keyboard shortcut
  3001.             to assign to this menu item as follows:
  3002.  
  3003.                A\0Save as...
  3004.  
  3005.             This will create a menu item using the shortcut "A"
  3006.             and the title "Save as...".
  3007.  
  3008.         LAMN_SubID (LONG) - Locale ID corresponding to the
  3009.             name of the new submenu item to create.
  3010.             You may precede the name with the keyboard shortcut
  3011.             to assign to this menu item as follows:
  3012.  
  3013.                A\0Save as...
  3014.  
  3015.             This will create a menu item using the shortcut "A"
  3016.             and the title "Save as...".
  3017.  
  3018.         LAMN_KeyText (STRPTR) - Pointer to the string whose first
  3019.             character will be used as the keyboard shortcut for
  3020.             this menu/submenu item.
  3021.  
  3022.         LAMN_KeyID (LONG) - Locale ID corresponding to the string whose
  3023.             first character will be used as the keyboard shortcut for
  3024.             this menu/submenu item.
  3025.  
  3026.         LAMN_CommandText (STRPTR) - Pointer to the string which
  3027.             will be used as the keyboard shortcut for this
  3028.             menu/submenu item.
  3029.  
  3030.         LAMN_CommandID (LONG) - Locale ID corresponding to the string
  3031.             which will be used as the keyboard shortcut for
  3032.             this menu/submenu item.
  3033.  
  3034.         LAMN_MutualExclude (ULONG) - Mutual exclusion information for
  3035.             this menu/submenu item.
  3036.  
  3037.         LAMN_UserData (APTR) - User data information for this
  3038.             menu/menu item/submenu item.
  3039.  
  3040.         LAMN_Disabled (BOOL) - Controls whether this
  3041.             menu/menu item/submenu item should be disabled.
  3042.  
  3043.         LAMN_CheckIt (BOOL) - Controls whether this menu/submenu item
  3044.             should be prepared to hold a checkmark. NOTE: This does
  3045.             not set the checkmark, use LAMN_Checked for this purpose.
  3046.  
  3047.         LAMN_Checked (BOOL) - Controls whether this menu/submenu item
  3048.             should be marked with a checkmark.
  3049.  
  3050.         LAMN_Toggle (BOOL) - Controls whether this menu/submenu item
  3051.             should be prepared to hold a checkmark the user is to
  3052.             toggle on demand. NOTE: this does not set the checkmark,
  3053.             use LAMN_Checked for this purpose.
  3054.  
  3055.         LAMN_Code (UWORD) - Raw key code to associate with this
  3056.             menu/submenu item. To find out if a rawkey event
  3057.             corresponds to this menu item use LT_FindMenuCommand.
  3058.  
  3059.         LAMN_Qualifier (ULONG) - Key qualifier to code to associate
  3060.             with this menu/submenu item. NOTE: the comparison does
  3061.             not distinguish between the left and right shift/caps/alt
  3062.             qualifier keys.
  3063.  
  3064.         LAMN_ID (ULONG) - Unique ID to associate with this
  3065.                           menu/menu item/submenu item. You can use this
  3066.                           later to look up this data using LT_GetMenuItem,
  3067.                           etc.
  3068.  
  3069.    EXAMPLE
  3070.  
  3071.         The following tagitem list:
  3072.  
  3073.             LAMN_TitelText,     "Project"
  3074.              LAMN_ItemText,     "New",
  3075.               LAMN_KeyText,     "N",
  3076.              LAMN_ItemText,     "Open...",
  3077.               LAMN_KeyText,     "O",
  3078.              LAMN_ItemText,     NM_BARLABEL,
  3079.              LAMN_ItemText,     "Save",
  3080.               LAMN_KeyText,     "S",
  3081.              LAMN_ItemText,     "A\0Save As...",
  3082.              LAMN_ItemText,     NM_BARLABEL,
  3083.              LAMN_ItemText,     "Print...",
  3084.               LAMN_KeyText,     "P",
  3085.              LAMN_ItemText,     NM_BARLABEL,
  3086.              LAMN_ItemText,     "Help...",
  3087.               LAMN_CommandText, "[Help]",
  3088.              LAMN_ItemText,     NM_BARLABEL,
  3089.              LAMN_ItemText,     "Quit...",
  3090.               LAMN_KeyText,     "Q",
  3091.             TAG_DONE
  3092.  
  3093.         Will create the following menu:
  3094.  
  3095.         +-------+
  3096.         |Project|
  3097.         +-------+------+
  3098.         |New         aN|
  3099.         |Open...     aO|
  3100.         |~~~~~~~~~~~~~~|
  3101.         |Save        aS|
  3102.         |Save As...  aA|
  3103.         |~~~~~~~~~~~~~~|
  3104.         |Print...    aP|
  3105.         |~~~~~~~~~~~~~~|
  3106.         |Help... [Help]|
  3107.         |~~~~~~~~~~~~~~|
  3108.         |Quit...     aQ|
  3109.         +--------------+
  3110.  
  3111.    RESULT
  3112.  
  3113.         Menu - Pointer to Menu structure, ready to pass to
  3114.                SetMenuStrip(), NULL on failure.
  3115.  
  3116.    SEE ALSO
  3117.  
  3118.         gtlayout.library/LT_FindCommandItem
  3119.         gtlayout.library/LT_GetMenuItem
  3120.         gtlayout.library/LT_LayoutMenuA
  3121.         gtlayout.library/LT_MenuControlTagList
  3122.         gtlayout.library/LT_NewMenuTemplate
  3123.         intuition.library/SetMenuStrip
  3124. gtlayout.library/LT_NewMenuTemplate            gtlayout.library/LT_NewMenuTemplate
  3125.  
  3126.    NAME
  3127.  
  3128.         LT_NewMenuTemplate -- Allocate and layout menu items (V11)
  3129.  
  3130.    SYNOPSIS
  3131.  
  3132.         Menu = LT_NewMenuTemplate(Screen,TextAttr,AmigaGlyph,CheckmarkGlyph,
  3133.          D0                         A0      A1        A2           A3
  3134.  
  3135.                                   Error,MenuTemplate);
  3136.                                     D0      D1
  3137.  
  3138.         
  3139.         struct Menu *LT_NewMenuTemplate(struct Screen *,struct TextAttr *,
  3140.                                         struct Image *,struct Image *,
  3141.                                         LONG *,struct NewMenu *);
  3142.  
  3143.    FUNCTION
  3144.  
  3145.         Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3146.  
  3147.    INPUTS
  3148.  
  3149.         Screen - Pointer to the screen the menu will appear on. This
  3150.                  parameter is required and must not be omitted.
  3151.  
  3152.         TextAttr - Pointer to the TextAttr that should be used to
  3153.                    layout the menus. If this parameter is omitted,
  3154.                    Screen->Font will be used instead.
  3155.  
  3156.         AmigaGlyph - Pointer to the Image to use as the Amiga glyph.
  3157.                      This parameter may be omitted.
  3158.  
  3159.                      NOTE: Ignored by intuition.library v37 and below.
  3160.  
  3161.         CheckmarkGlyph - Pointer to the Image to use as the checkmark
  3162.                          glyph. This parameter may be omitted.
  3163.  
  3164.         Error - Pointer to receive error code in case the menu
  3165.                 creation or layout process fails. This parameter
  3166.                 may be omitted.
  3167.  
  3168.         MenuTemplate - Pointer to a series of NewMenu structures,
  3169.                        just as you would pass to
  3170.                        gtlayout.library/LT_LayoutMenuA.
  3171.  
  3172.    NOTES
  3173.  
  3174.         The menu created by this function cannot be used with the
  3175.         routines LT_MenuControlTagList, LT_FindMenuCommand and
  3176.         LT_GetMenuItem.
  3177.  
  3178.    RESULT
  3179.  
  3180.         Menu - Pointer to Menu structure, ready to pass to
  3181.                SetMenuStrip(), NULL on failure.
  3182.  
  3183.    SEE ALSO
  3184.  
  3185.         gtlayout.library/LT_LayoutMenuA
  3186.         gtlayout.library/LT_NewMenuTagList
  3187.         intuition.library/SetMenuStrip
  3188. gtlayout.library/LT_PressButton                gtlayout.library/LT_PressButton
  3189.  
  3190.    NAME
  3191.  
  3192.         LT_PressButton -- Highlight a button so it looks as if the user
  3193.                           has selected it.
  3194.  
  3195.    SYNOPSIS
  3196.  
  3197.         LT_PressButton(Handle,ID);
  3198.                           A0  D0
  3199.  
  3200.         VOID LT_PressButton(LayoutHandle *,LONG);
  3201.  
  3202.    FUNCTION
  3203.  
  3204.         You can provide visual feedback for BUTTON_KIND objects by calling
  3205.         this routine. They will briefly appear to be selected and then
  3206.         fall back to their original states.
  3207.  
  3208.    INPUTS
  3209.  
  3210.         Handle - Pointer to LayoutHandle structure
  3211.  
  3212.         ID - ID of button object to highlight
  3213.  
  3214.    RESULT
  3215.  
  3216.         none
  3217. gtlayout.library/LT_RebuildTagList          gtlayout.library/LT_RebuildTagList
  3218.  
  3219.    NAME
  3220.  
  3221.         LT_RebuildTagList -- Rebuild the user interface after modifying it.
  3222.  
  3223.    SYNOPSIS
  3224.  
  3225.         Success = LT_RebuildTagList(Handle,Clear,TagList);
  3226.            D0                         A0    D0     A1
  3227.  
  3228.         BOOL LT_RebuildTagList(LayoutHandle *,BOOL,struct TagItem *);
  3229.  
  3230.         Success = LT_RebuildTags(Handle,Clear,...);
  3231.  
  3232.         BOOL LT_RebuildTags(LayoutHandle *,BOOL,...);
  3233.  
  3234.    FUNCTION
  3235.  
  3236.         Certain aspects of the user interface can be changed at run time,
  3237.         such as button labels. This routine will let you rebuild the interface
  3238.         based upon the data supplied at creation time and your subsequent
  3239.         changes. Before you make any vital changes, it is recommended to
  3240.         lock the window using LT_LockWindow() in order to avoid clashes
  3241.         with the Intuition and GadTools subsystems.
  3242.  
  3243.    INPUTS
  3244.  
  3245.         Handle - Pointer to LayoutHandle structure.
  3246.  
  3247.         Clear - Pass in TRUE if you wish to have the window contents
  3248.                 cleared before they are rebuild. This will introduce
  3249.                 some visual hashing.
  3250.  
  3251.         TagList - Attributes controlling the layout process.
  3252.  
  3253.    RESULT
  3254.  
  3255.         Success - TRUE indicates that the interface was rebuilt,
  3256.                   FALSE indicates trouble; it is recommended to
  3257.                   call LT_DeleteHandle() on your LayoutHandle as
  3258.                   soon as possible as the previous operation may
  3259.                   have left the user interface in an inoperable
  3260.                   state.
  3261.  
  3262.    TAGS
  3263.  
  3264.         LAWN_Bounds (struct IBox *) - Boundaries in which the window
  3265.             should be centered.
  3266.  
  3267.         LAWN_ExtraWidth (LONG) - Extra space to add to the window
  3268.             width.
  3269.  
  3270.         LAWN_ExtraHeight (LONG) - Extra height to add to the window
  3271.             height.
  3272. gtlayout.library/LT_ReplyIMsg                    gtlayout.library/LT_ReplyIMsg
  3273.  
  3274.    NAME
  3275.  
  3276.         LT_ReplyIMsg -- Dispose of an IntuiMessage received
  3277.  
  3278.    SYNOPSIS
  3279.  
  3280.         LT_ReplyIMsg(IntuiMessage);
  3281.                          A0
  3282.  
  3283.         VOID LT_ReplyIMsg(struct IntuiMessage *);
  3284.  
  3285.    FUNCTION
  3286.  
  3287.         This routine complements LT_GetIMsg().
  3288.  
  3289.    INPUTS
  3290.  
  3291.         IntuiMessage - Pointer to IntuiMessage structure,
  3292.                        passing NULL is harmless.
  3293.  
  3294.    NOTES
  3295.  
  3296.         Only pass IntuiMessages you received via LT_GetIMsg,
  3297.         or things will get tough.
  3298.  
  3299.    RESULT
  3300.  
  3301.         none
  3302.  
  3303.    SEE ALSO
  3304.  
  3305.         gtlayout.library/LT_GetIMsg
  3306. gtlayout.library/LT_SetAttributesA          gtlayout.library/LT_SetAttributesA
  3307.  
  3308.    NAME
  3309.  
  3310.         LT_SetAttributesA -- Change object attributes
  3311.  
  3312.    SYNOPSIS
  3313.  
  3314.         LT_SetAttributesA(Handle,ID,Tags);
  3315.                             A0   D0  A1
  3316.  
  3317.         VOID LT_SetAttributes(LayoutHandle *,LONG,struct TagItem *);
  3318.  
  3319.         LT_SetAttributes(Handle,ID,...);
  3320.  
  3321.         VOID LT_SetAttributes(LayoutHandle *,LONG,...);
  3322.  
  3323.    FUNCTION
  3324.  
  3325.         This routine passes the tag item list it gets directly
  3326.         over to GT_SetGadgetAttrsA(), so any tag items valid for
  3327.         gadtools.library can be used here as well. Some filtering
  3328.         may be done in order to stop objects from getting redrawn
  3329.         if this is not absolutely necessary.
  3330.  
  3331.    INPUTS
  3332.  
  3333.         Handle - Pointer to LayoutHandle.
  3334.  
  3335.         ID - ID number of the object to change. This is the same value
  3336.              you passed via LA_ID to LT_New() when you created this object.
  3337.  
  3338.         Tags - Attributes controlling object states.
  3339.  
  3340.    TAGS
  3341.  
  3342.         All gadtools.library tags are allowed, but not all are supported.
  3343.         In addition to these tags a few additional tag values are
  3344.         supported:
  3345.  
  3346.         LH_AutoActivate (BOOL) - Set to TRUE if you want the interface
  3347.             to always keep a string gadget active if possible. Hitting
  3348.             the return key will then cause the next following string
  3349.             gadget to get activated, either cycling through all the
  3350.             string gadgets available or stopping at the next string
  3351.             gadget to have the LAST_LastGadget attribute set.
  3352.  
  3353.         LH_UserData (APTR) - Store user specific data in the
  3354.             LayoutHandle->UserData entry.
  3355.             (requires gtlayout.library v9 or higher)
  3356.  
  3357.         LH_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  3358.             events.
  3359.             Default: TRUE
  3360.             (requires gtlayout.library v13 or higher)
  3361.  
  3362.         LH_LocaleHook (struct Hook *) - The hook to call when
  3363.             locale string IDs are to be mapped to strings. The
  3364.             hook function is called with the following parameters:
  3365.  
  3366.             String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  3367.               D0                            A0                         A2
  3368.                               LONG ID)
  3369.                                    A1
  3370.  
  3371.             The function is to look up the string associated with the ID
  3372.             passed in and return the string.
  3373.  
  3374.         LH_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  3375.             of with LT_DeleteHandle() all variables maintained by the
  3376.             input handling code will be flushed. For example, if you
  3377.             would use the LA_STRPTR tag for STRING_KIND objects the
  3378.             last string gadget contents would be copied into the buffer
  3379.             pointed to by LA_STRPTR. If you do not want to use this
  3380.             feature, disable it with "LH_ExitFlush,FALSE".
  3381.             Default: TRUE
  3382.             (requires gtlayout.library v9 or higher)
  3383.  
  3384.         GAUGE_KIND:
  3385.  
  3386.             LAGA_Percent (LONG) - Percentage of the gauge to fill.
  3387.  
  3388.             LAGA_InfoText (STRPTR) - Text to be printed within the
  3389.                 gauge display, such as a percentage number.
  3390.  
  3391.         BOX_KIND:
  3392.  
  3393.             LABX_Index (LONG) - The number of the line to change, this
  3394.                 tag works in conjunction with the LABX_Text tag.
  3395.  
  3396.             LABX_Text (STRPTR) - The text to put into the line indicated
  3397.                 by the LABX_Index tag.
  3398.  
  3399.             LABX_Lines (STRPTR *) - The text to set for the box contents,
  3400.                 terminate the text array with NULL.
  3401.  
  3402.         HORIZONTAL_KIND:
  3403.         VERTICAL_KIND:
  3404.  
  3405.             LAGR_ActivePage (LONG) - Index number of page to display
  3406.                 witthin the group. NOTE: requires that this group was
  3407.                 created with the LAGR_ActivePage attribute set.
  3408.  
  3409.         FRACTION_KIND:
  3410.  
  3411.             LAFC_Number (FIXED) - Fixed point number to use
  3412.  
  3413.             LAFC_Min (FIXED) - Minimum allowed value for this
  3414.                 object.
  3415.  
  3416.             LAFC_Max (FIXED) - Maximum allowed value for this
  3417.                 object.
  3418.  
  3419.         INTEGER_KIND:
  3420.  
  3421.             LAIN_Min (LONG) - Minimum allowed value for this
  3422.                 object.
  3423.  
  3424.             LAIN_Max (LONG) - Maximum allowed value for this
  3425.                 object.
  3426.  
  3427.         PASSWORD_KIND:
  3428.  
  3429.             LAPW_String (STRPTR) - Secret text to use
  3430.  
  3431.         STRING_KIND:
  3432.  
  3433.             LAST_CursorPosition (LONG) - Repositions the cursor,
  3434.                 pass -1 to move it to the end of the string.
  3435.                 (requires gtlayout.library v7 or higher)
  3436.  
  3437.         TAPEDECK_KIND:
  3438.  
  3439.             LATD_Pressed (BOOL) - TRUE to make this button shown
  3440.                 as pressed, FALSE to show it in depressed state.
  3441.  
  3442.         BOOPSI_KIND:
  3443.  
  3444.             All tags are passed straight through to SetGadgetAttrs(..).
  3445.  
  3446.         All objects:
  3447.  
  3448.             LA_LabelText (STRPTR) - New gadget label text to use.
  3449.  
  3450.             LA_LabelID (LONG) - Locale text ID to use for this object.
  3451.  
  3452.    RESULT
  3453.  
  3454.        none
  3455. gtlayout.library/LT_ShowWindow                  gtlayout.library/LT_ShowWindow
  3456.  
  3457.    NAME
  3458.  
  3459.         LT_ShowWindow -- Make a window visible
  3460.  
  3461.    SYNOPSIS
  3462.  
  3463.         LT_ShowWindow(Handle,Activate);
  3464.                         A0      A1
  3465.  
  3466.         VOID LT_ShowWindow(LayoutHandle *,BOOL);
  3467.  
  3468.    FUNCTION
  3469.  
  3470.         The window attached to a LayoutHandle is made visible, this
  3471.         involves bringing it to the front, bringing the screen to
  3472.         the front the window resides on, unzooming the window and
  3473.         also moving the visible part of an autoscrolling screen.
  3474.  
  3475.    INPUTS
  3476.  
  3477.         Window - Pointer to Window structure.
  3478.  
  3479.         Activate - If TRUE the window will be activated as soon
  3480.             as it has been brought to the front.
  3481.  
  3482.         The arguments are passed in A0 and A1, this is *not* a
  3483.         typo.
  3484.  
  3485.    RESULT
  3486.  
  3487.         none
  3488. gtlayout.library/LT_String2Fixed              gtlayout.library/LT_String2Fixed
  3489.  
  3490.    NAME
  3491.  
  3492.         LT_String2Fixed -- Convert an ASCII string into a fixed-point numeric
  3493.                            value.
  3494.  
  3495.    SYNOPSIS
  3496.  
  3497.         Fixed = LT_String2Fixed(String)
  3498.           D0                      A0
  3499.  
  3500.         FIXED LT_String2Fixed(STRPTR);
  3501.  
  3502.    FUNCTION
  3503.  
  3504.         This routine complements LT_Fixed2String, it implements a
  3505.         service similar to atof() in converting an ASCII string
  3506.         into a fixed-point number.
  3507.  
  3508.    INPUTS
  3509.  
  3510.         String - Pointer to null-terminated string.
  3511.  
  3512.    RESULT
  3513.  
  3514.         Fixed - Fixed-point number; will be 0.0 if non-numeric
  3515.                 characters are found in the input string.
  3516.  
  3517.    NOTES
  3518.  
  3519.         The decimal point to look for will be taken from the
  3520.         current locale settings. If locale.library is not
  3521.         installed, the `.' character will be used instead.
  3522. gtlayout.library/LT_UnlockWindow              gtlayout.library/LT_UnlockWindow
  3523.  
  3524.    NAME
  3525.  
  3526.         LT_UnlockWindow -- The complement to LT_LockWindow().
  3527.  
  3528.    SYNOPSIS
  3529.  
  3530.         LT_UnlockWindow(Window);
  3531.                           A0
  3532.  
  3533.         VOID LT_UnlockWindow(struct Window *);
  3534.  
  3535.    FUNCTION
  3536.  
  3537.         This routine unlocks a window locked using LT_LockWindow, freeing
  3538.         allocated memory, restoring the window characteristics to their
  3539.         original values.
  3540.  
  3541.    INPUTS
  3542.  
  3543.         Window - Pointer to window structure.
  3544.  
  3545.    RESULT
  3546.  
  3547.         none
  3548. gtlayout.library/LT_UpdateStrings       gtlayout.library/LT_UpdateStrings
  3549.  
  3550.    NAME
  3551.  
  3552.         LT_UpdateStrings -- Make sure all visible string buffer contents
  3553.                             get written into storage.
  3554.  
  3555.                             (requires gtlayout.library v9 or higher)
  3556.  
  3557.    SYNOPSIS
  3558.  
  3559.         LT_UpdateStrings(LayoutHandle);
  3560.                                 A0
  3561.  
  3562.         VOID LT_UpdateStrings(struct LayoutHandle *);
  3563.  
  3564.    FUNCTION
  3565.  
  3566.         The user can terminate input into a string gadget or an object
  3567.         derived from a string gadget by various means. They all have
  3568.         in common that the application receives no notification that
  3569.         the string gadget contents have changed. This is particularly
  3570.         nasty with objects which make use of LA_STRPTR or other
  3571.         tags. Using LT_UpdateStrings() you can force all visible string
  3572.         gadget objects to hand over their contents to the internal
  3573.         buffers. Do this before you eventually exit your input loop.
  3574.  
  3575.    INPUTS
  3576.  
  3577.         LayoutHandle - Pointer to LayoutHandle structure.
  3578.  
  3579.    RESULT
  3580.  
  3581.         none
  3582.