home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d911 / gadlayout.lha / GadLayout / gadlayout.doc < prev    next >
Text File  |  1993-10-03  |  18KB  |  350 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadlayout/FreeLayoutGadgets
  4. gadlayout/GadgetArrayIndex
  5. gadlayout/GL_SetGadgetAttrsA
  6. gadlayout/LayoutGadgetsA
  7. gadlayout/FreeLayoutGadgets                       gadlayout/FreeLayoutGadgets
  8.  
  9.    NAME
  10.        FreeLayoutGadgets -- Frees gadgets laid out with LayoutGadgets().
  11.  
  12.    SYNOPSIS
  13.        FreeLayoutGadgets(gad_info);
  14.        VOID FreeLayoutGadgets(APTR);
  15.  
  16.    FUNCTION
  17.        Frees all resources used in creating and laying out gadgets with
  18.        LayoutGadgets().  This frees all gadgets as well as other
  19.        resources used.  Generally this will be called after a call to
  20.        CloseWindow() in Intuition.
  21.  
  22.    INPUTS
  23.        gad_info - The pointer returned by LayoutGadgets().
  24.  
  25.    SEE ALSO
  26.        LayoutGadgetsA()
  27.  
  28. gadlayout/GadgetArrayIndex                         gadlayout/GadgetArrayIndex
  29.  
  30.    NAME
  31.        GadgetArrayIndex -- Get a gadget's index in the LayoutGadget array.
  32.  
  33.    SYNOPSIS
  34.        i = GadgetArrayIndex(gad_id, gadgets)
  35.        WORD GadgetArrayIndex(WORD, struct LayoutGadget *)
  36.  
  37.    FUNCTION
  38.        Given a gadget ID, returns the index of that gadget's definition
  39.        in the LayoutGadget array.  For example, in cases where you need
  40.        to know a gadget's Gadget structure (eg. if you wanted to use
  41.        the Intuition function ActivateGadget() to make a string or an
  42.        integer gadget active), you would need to lookup the lg_Gadget
  43.        field in the LayoutGadget array.  You MUST NOT GIVE THE ARRAY
  44.        INDEX YOURSELF, THIS IS NOT GUARUNTEED TO REMAIN VALID!  Instead,
  45.        pass the id of the gadget that you want and this function will
  46.        return the array index for you.
  47.  
  48.    INPUTS
  49.        gad_id - The ID of the gadget you want to find.
  50.        gadgets - The LayoutGadget array that this gadget is defined in.
  51.  
  52.    RESULT
  53.        i - The index into the LayoutGadget array of the entry of the
  54.           gadget ID you asked for.
  55.  
  56. gadlayout/GL_SetGadgetAttrsA                     gadlayout/GL_SetGadgetAttrsA
  57.  
  58.    NAME
  59.        GL_SetGadgetAttrsA -- Change attributes of a GadLayout gadget.
  60.        GL_SetGadgetAttrs -- Varargs stub for GL_SetGadgetAttrsA.
  61.  
  62.    SYNOPSIS
  63.        GL_SetGadgetAttrsA(gad_info, gad, win, req, taglist)
  64.        VOID GL_SetGadgetAttrsA(APTR, struct Gadget *, struct Window *,
  65.                                struct Requester *, struct TagItem *)
  66.  
  67.        GL_SetGadgetAttrs(gad_info, gad, win, req, firsttag, ...)
  68.        VOID GL_SetGadgetAttrs(APTR, struct Gadget *, struct Window *,
  69.                               struct Requester *, Tag *, ...)
  70.  
  71.    FUNCTION
  72.        Changes attributes for one of the GadLayout gadget kinds according
  73.        according to the attributes chosen in the tag list.
  74.  
  75.    INPUTS
  76.        gad_info - The value returned by LayoutGadgetsA().
  77.        gad - Pointer to the gadget in question.
  78.        win - Pointer to the window containing the gadget.
  79.        req - Pointer to the requester containing the gadget, or NULL if
  80.            not in a requester. (Not implemented yet, use NULL.)
  81.        taglist - Pointer to a TagItem list.
  82.  
  83.    TAGS
  84.        IMAGEBUTTON_KIND:
  85.        GLIM_Image (struct Image *) - Changes the image displayed in the
  86.            gadget.
  87.  
  88.    BUGS
  89.        This function is not compatable with itself in versions releases
  90.        1.5 and lower, because of the new pi parameter!  ALL OLD CODE
  91.        WILL HAVE TO BE CHANGED!!!
  92.  
  93.        Attributes not pertaining to a specific gadget kind will not
  94.        always be ignored, so you will need to be careful that you only
  95.        try to change attributes that are valid for the gadget's kind.
  96.  
  97. gadlayout/LayoutGadgetsA                             gadlayout/LayoutGadgetsA
  98.  
  99.    NAME
  100.        LayoutGadgetsA -- Formats an array of GadTools gadgets.
  101.        LayoutGadgets -- Varargs stub for LayoutGadgetsA().
  102.  
  103.    SYNOPSIS
  104.        gad_info = LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  105.        APTR LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  106.                            struct Screen *, struct TagItem *)
  107.  
  108.        gad_info = LayoutGadgets(gad_list, gadgets, screen, firsttag, ...)
  109.        APTR LayoutGadgets(struct Gadget **, struct LayoutGadget *,
  110.                           struct Screen *, Tag *, ...)
  111.  
  112.    FUNCTION
  113.        Creates a laid-out gadget list from a LayoutGadget array, which
  114.        describes each gadget you want to create.  Gadgets you create
  115.        can be any of the gadget kinds supported by GadTools, as well
  116.        as any of the extended gadget kinds provided by GadLayout.
  117.        Gadgets can easily be defined so that the automatically adjust
  118.        their sizes and positions to accomodate fonts of any size
  119.        (including proportional fonts) and also to adapt to different
  120.        locale strings.  The real power of GadLayout is that allows you
  121.        to create a gadget layout that dynamically adjusts to different
  122.        user's environments.
  123.  
  124.    INPUTS
  125.        gad_list - Pointer to the gadget list pointer, this will be
  126.            ready to pass to OpenWindowTags() or AddGList().
  127.  
  128.        gadgets - An array of LayoutGadget structures.  Each element
  129.            in the array describes one of the gadgets that you will
  130.            be creating.  Each LayoutGadget structure in the array
  131.            should be initialized as follows:
  132.  
  133.            lg_GadgetID - The ID for this gadget.
  134.            lg_LayoutTags - A taglist consisting of the following tags:
  135.                GL_GadgetKind (ULONG) - Which gadget kind to use.  This
  136.                    may be any of the GadTools gadget kinds (defined in
  137.                    libraries/gadtools.h), or one of the additional kinds
  138.                    provided by GadLayout, which are:
  139.                    IMAGEBUTTON_KIND : A button gadget with that uses an
  140.                                       Intuition Image structure for its
  141.                                       contents.  The image will be centred
  142.                                       automatically.
  143.                    DRAWER_KIND : A drawer button gadget.  Use this to
  144.                                  allow the user to use the ASL file
  145.                                  requester to select a path.
  146.                    FILE_KIND : A file button gadget.  Use this to allow
  147.                                the user to use the ASL file requester
  148.                                to select a file.
  149.                    Additional kinds may be added in the future.
  150.                GL_Width (WORD) - Absolute gadget width, in pixels.
  151.                GL_DupeWidth (UWORD) - Duplicate the width of another
  152.                    gadget.
  153.                GL_AutoWidth (WORD) - Set width according to length of
  154.                    text label + ti_Data.  Note that this function
  155.                    does not take into account the amount of space any
  156.                    gadget imagery might take within the gadgets area.
  157.                GL_Columns (UWORD) - Set width of gadget so that
  158.                    approximately ti_Data columns of text with the
  159.                    gadget's font will fit.  This will only be an
  160.                    approximation, because with proportional fonts the
  161.                    width of character varies.  Note that this function
  162.                    does not take into account the amount of space any
  163.                    gadget imagery might take within the gadgets area.
  164.                GL_AddWidth (WORD) - Add some value to the total width
  165.                    calculation.
  166.                GL_MinWidth (WORD) - Make sure that the final width of
  167.                    the gadget is at least this.
  168.                GL_MaxWidth (WORD) - Make sure that the final width of
  169.                    the gadget is at most this.
  170.                GL_Height (WORD) - Absolute gadget width.
  171.                GL_HeightFactor (UWORD) - Make the gadget height a multiple
  172.                    of the font height (useful for LISTVIEW_KIND gadgets).
  173.                GL_AutoHeight (WORD) - Set height according to height of
  174.                    text font + ti_Data.
  175.                GL_AddHeight (WORD) - Add some value to the total height
  176.                    calculation.
  177.                GL_MinHeight (WORD) - Make sure that the final height of
  178.                    the gadget is at least this.
  179.                GL_MaxHeight (WORD) - Make sure that the final height of
  180.                    the gadget is at most this.
  181.                GL_Top (WORD) - Absolute top edge.
  182.                GL_TopRel (UWORD)  - Top edge relative to bottom edge of
  183.                    another gadget (specified by its gadget ID).
  184.                GL_AdjustTop (WORD) - ADD the height of the text font +
  185.                    ti_Data to the top edge (often used to to properrly
  186.                    position gadgets that have their label above).
  187.                GL_AddTop (WORD) -  Add some value to the final top edge
  188.                    calculation.
  189.                GL_Bottom (WORD) - Absolute bottom edge.
  190.                GL_BottomRel (UWORD) - Bottom edge relative to top edge of
  191.                    another gadget (specified by its gadget ID).
  192.                GL_AddBottom (WORD) - Add some value to the final bottom edge
  193.                    calculation.
  194.                GL_Left (WORD) - Absolute left edge.
  195.                GL_LeftRel (UWORD) - Left edge relative to right edge of
  196.                    another gadget (specified by its gadget ID).
  197.                GL_AdjustLeft (WORD) - ADD the width of the text label +
  198.                    ti_Data to the left edge.
  199.                GL_AlignLeft (UWORD) - Align the left edge of the gadget
  200.                    with the left edge of another gadget (specified by its
  201.                    gadget ID).
  202.                GL_AddLeft (WORD) - Add some value to the final left edge
  203.                    calculation.
  204.                GL_Right (WORD) - Absolute right edge.
  205.                GL_RightRel (UWORD) - Right edge relative to left edge of
  206.                    another gadget (specified by its gadget ID).
  207.                GL_AlignRight (UWORD) - Align the right edge of the gadget
  208.                    with the right edge of another gadget (specified by its
  209.                    gadget ID).
  210.                GL_AddRight (WORD) - Add some value to the final right edge
  211.                    calculation.
  212.                GL_GadgetText (STRPTR) - Gadget text label.
  213.                GL_TextAttr (struct TextAttr *) - Desired font for gadget
  214.                    label, will override the GL_DefTextAttr if used.
  215.                GL_Flags - (ULONG) Gadget flags.
  216.                GL_UserData (VOID *)- Gadget UserData.
  217.                GL_LocaleText - Gadget label taken from a locale catalog,
  218.                    you supply the locale string ID.  If you use this tag
  219.                    you MUST have used GL_AppStrings in your call to
  220.                    LayoutGadgets().
  221.  
  222.                If you've specified one of GadLayout's own gadget kinds
  223.                with GL_GadgetKind, the following tags are available for
  224.                defining attributes of those gadgets:
  225.  
  226.                GLIM_Image (struct Image *) - Provide a pointer to the
  227.                    Image structure to to be used in an IMAGEBUTTON_KIND
  228.                    structure.  This pointer only need be valid when
  229.                    LayoutGadgets() is called.
  230.                GLIM_ReadOnly (BOOL) - Specifies that the gadget is read-
  231.                    only.  It will get a recessed border and will not be
  232.                    highlighted when clicked on.
  233.  
  234.                Generally you need only specify the tags when the data
  235.                has changed from the previously gadget.  This gets a
  236.                little tricky when you use the relation tags like
  237.                GL_TopRel, as this means that gadgets will not be
  238.                processed in sequential order necessarily.
  239.  
  240.            lg_GadToolsTags - When defining a GadTools gadgets, you
  241.                can pass a GadTools taglist to set options for that
  242.                gadget.  This would be the same set of tags that you
  243.                might pass to CreateGadgetA() if you were using GadTools
  244.                directly.
  245.            lg_Gadget - The pointer to the Gadget structure created for
  246.                this gadget will be placed here.  You should initialize
  247.                this field to NULL.  WARNING: The gadget structure
  248.                created READ-ONLY!
  249.  
  250.        screen - A pointer to the screen that the gadgets will be
  251.            created for.  The is required so that the layout routines
  252.            can get display info about the screen, no rendering will
  253.            be done.
  254.  
  255.        taglist - Pointer to a TagItem list (see below for allowed tags)
  256.  
  257.    TAGS
  258.        GL_RightExtreme (LONG *) - A pointer to a LONG where GadLayout
  259.            will put the co-ordinate of the rightmost point where any
  260.            imagery of the laid-out gadgets will be drawn.  Use this to
  261.            open a window exactly big enough to hold all your gadgets.
  262.            Use this value alone with the WA_InnerWidth window tag and
  263.            NOT WA_Width, since you do not know how big the window
  264.            border will be.
  265.        GL_LowerExtreme (LONG *) - A pointer to a LONG where GadLayout
  266.            will put the co-ordinate of the lowermost point where any
  267.            imagery of the laid-out gadget will be drawn.  Use this to open
  268.            a window exactly big enough to hold all your gadgets.
  269.            Use this value alone with the WA_InnerHeight window tag and
  270.            NOT WA_Height, since you do not know how big the window
  271.            border will be.
  272.        GL_DefTextAttr (struct TextAttr *) - Instead of having to indicate
  273.            a TextAttr for each gadget, you can specify a font to be used
  274.            by default for all your gadgets.
  275.        GL_Catalog (struct Catalog *) - Specify the locale catalog to use
  276.            to get your strings from.  If you wish to localize your gadget
  277.            string via GL_LocaleText you MUST use this tag as well as
  278.            GL_AppStrings.  You must also make certain that locale.library
  279.            has been opened successfully with LocaleBase pointing to the
  280.            library base.
  281.        GL_AppStrings (struct AppString **) - If you wish to make your
  282.            gadgets localized, you you must pass a list of strings and
  283.            their IDs.  The format of these strings is an array of
  284.            structures, with a LONG that contains the ID and a STRPTR
  285.            pointing to the string, i.e.:
  286.                struct AppString
  287.                {
  288.                    LONG   as_ID;
  289.                    STRPTR as_Str;
  290.                };
  291.            These strings serve as the default language for the gadgets.
  292.            See locale.library documentation for more information on
  293.            localizing applications.  You MUST use this tag in addition to
  294.            GL_Catalog if you wish to use GL_LocaleText to localize your
  295.            gadgets.
  296.        GL_NoCreate (BOOL) - Set to TRUE if you don't want the layout
  297.            routine to actually create any gadgets.  This is used when
  298.            you want to use the GL_RightExtreme and GL_LowerExtreme tags
  299.            to find out how much space your gadgets will take, but don't
  300.            actually want to create the gadgets just yet.
  301.        GL_BorderTop (UWORD) - The size of the top border of your window.
  302.            If your window does not have the WFLG_GIMMEZEROZERO flag set,
  303.            it will be necessary to pass the size of the window borders.
  304.            This value can be gotten either from the Window structure of
  305.            your window (if it is already open), or from the Screen
  306.            structure of your screen (see intuition/screens.h for details
  307.            about this).  NOTE: This value is NOT added to the value
  308.            returned by GL_LowerExtreme!
  309.        GL_BorderLeft (UWORD) - The size of the left border of your window.
  310.            If your window does not have the WFLG_GIMMEZEROZERO flag set,
  311.            it will be necessary to pass the size of the window borders.
  312.            This value can be gotten either from the Window structure of
  313.            your window (if it is already open), or from the Screen
  314.            structure of your screen (see intuition/screens.h for details
  315.            about this).  NOTE: This value is NOT added to the value
  316.            returned by GL_RightExtreme.
  317.  
  318.    RESULT
  319.        gad_info - A pointer to a private structure.  You must keep this
  320.            value and pass it to FreeLayoutGadgets() later on in order to
  321.            free up all resources used by your gadgets.
  322.  
  323.    NOTES
  324.        You must be careful with the taglist in the lg_LayoutTags field.
  325.        Tags are processed sequentally in the order you give them in, and
  326.        if a tag references another gadget (eg. the GL_TopRel tag), then
  327.        processing of the current gadget halts while the referenced gadget
  328.        is processed (if it has not already been processed).  Problems can
  329.        arise if this gadget refers back to the original gadget that
  330.        referenced it, if it is referring to a field that has not yet been
  331.        processed in that gadget.  For example, gadget GAD_BUTTON1 may use
  332.        the GL_TopRel tag to refer to GAD_BUTTON2, which may subsequently
  333.        make use of GL_LeftRel to refer back to GAD_BUTTON1.  The gadgets
  334.        left edge must already be defined in GAD_BUTTON1 (i.e. a tag such
  335.        as GL_Left MUST appear before the GL_TopRel tag) if GAD_BUTTON2 is
  336.        to get the left edge desired.
  337.  
  338.    BUGS
  339.        Doesn't do any checking to make sure gadgets don't overlap.
  340.        Essentially assumes you know what you're doing with the layout.
  341.  
  342.        Bad things will happen if you provide an IMAGEBUTTON_KIND gadget
  343.        with an image too big to fit within the dimensions you've provided
  344.        for the gadget.
  345.  
  346.    SEE ALSO
  347.        FreeLayoutGadgets(), gadlayout/gadlayout.h, libraries/gadtools.h,
  348.        GadTools documentation.
  349.  
  350.