[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]


    NAME
        layout.gadget-- An automatic GUI layout arrangement gadget.

    SUPERCLASS
        gadgetclass

    REQUIRES
        bevel.image

    DESCRIPTION
        The layout gadget is used to automatically calculate the
        positions and sizes of BOOPSI gadgets and images in a resizable
        window. Instead of handling the positions of gadgets by hand,
        you can just describe your window layout in a hierarchical
        fashion, and the layout gadget will do the rest.

        The basic method of layout of a group is as follows:
        - Calculate the minimum and maximum size of each gadget.
        - Calculate the weight totals for the group. Substract the size
          of the fixed size (weighted size 0) gadgets from the total
          size of the group.
        - Distribute the remaining space in the group according to the
          relative weighs of the children.
        - If extra space remains, distribute it evenly between the
          children.

        PRIVATE METHODS
                LAYOUT_ACTIVATEOBJECT -- Used by activatelayoutgadget(), sets
                the handleinput path to a gadget somewhere in a layout hierarchy.

                LAYOUT_TABCYCLE -- Sets the gadget attributes based on the
                gadget in the end of the handleinput path.

                LAYOUT_FIRSTCYCLE -- Sets the handleinput path to the first tab
                cycle gadget in a layout hierarchy.

                LAYOUT_LASTCYCLE -- Sets the handleinput path to the last tab
                cycle gadget in a layout hierarchy.

                LAYOUT_FLUSHDOMAINS -- Flushes all domain caches below a certain
                level.

                LAYOUT_FINDKEY -- Find a gadget with a key in the CommKey list.

                LAYOUT_FINDACTIVE -- Find the active gadget pointer.

                LAYOUT_FINDHELP -- Find the last gadget that returned helphit.

    METHODS
        GM_HANDLEINPUT -- Passed to the currently active child

        GM_DOMAIN -- Passed to all children

        GM_RENDER -- Passed to all children When invoked
            by input.device, the stack is first swapped to provide
            more workspace.

        GM_LAYOUT -- Passed to all children after first setting
            their size and position with SetAttrs. When invoked
            by input.device, the stack is first swapped to provide
            more workspace.

        GM_HITTEST -- Passed to the child in whose domain
            rectangle the pointer is

        GM_HELPTEST -- Passed to the child in whose domain
            rectangle the pointer is

        GM_GOACTIVE -- Passed to the currently "active" child (one
            that returned GM_HITTEST)

        GM_GOINACTIVE -- Passed to the currently active child

        OM_SET -- Passed to superclass after scanning the
            taglist for layout specific tags

        OM_UPDATE -- Passed to superclass after scanning the
            taglist for layout specific tags

        OM_GET -- Passed to superclass for non-layout tags

        OM_NEW -- Passed to superclass, then adding all the
            children on the taglist to the private list.

        OM_DISPOSE -- Passed to all children (thus disposing all
            of them), then to superclass.

        GM_CLIPRECT -- Passed to all children.

        DTM_PROCLAYOUT -- Like GM_LAYOUT, but passes DTM_PROCLAYOUT
            forward. Useful if the layout group contains only
            datatype objects.

        All other methods are passed to the superclass.

  ATTRIBUTES
      Attributes global to the whole layout group. Pass all of these
      BEFORE adding child objects:

      GA_ReadOnly (BOOL)
          Disables input to the entire layout group and its chidren.
          This tag is NOT propagated to children. The input blocking
          occurs within the layout object itself.

          Defaults to FALSE

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      GA_Disabled (BOOL)
          Disables entire layout group and its chidren. This tag
          is propagated all children. When setting/clearing this
          tag, take care to re-set/re-clear any children you want
          included from this mass disabling ability.

          Defaults to FALSE

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      GA_TextAttr (struct textattr *)
          The font that will be used for the group label.

          Defaults to NULL (uses rastport default font).

          Applicability is (OM_NEW)

      LAYOUT_Orientation (ULONG)
          Whether the objects of this group are arranged horizontally or
          vertically. Possible values are LORIENT_HORIZONTAL and
          LORIENT_VERTICAL.

          Defaults to LORIENT_HORIZONTAL.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_FixedHoriz (BOOL)
          Whether the width of this layout group is fixed to the width
          assigned by the window or parent layout group. If set to FALSE,
          the gadget will minimize its width to the smallest possible
          value. Generally you will have to also set LAYOUT_ShrinkWrap
          (below) to TRUE also. It is recommended that this tag is used
          only in the top layout group. Using a weighted width of 0 gives
          more predictable results elsewhere.

          Defaults to TRUE.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_FixedVert (BOOL)
          Whether the height of this layout group is fixed to the height
          assigned by the window or parent layout group. If set to FALSE,
          the gadget will minimize its height to the smallest possible
          value. Generally you will have to also set LAYOUT_ShrinkWrap
          (below) to TRUE also. It is recommended that this tag is used
          only in the top layout group. Using a weighted height of 0 gives
          more predictable results elsewhere.

          Defaults to TRUE.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_HorizAlignment (ULONG)
          The horizontal alignment of the objects in this layout group.
          Possible values are LALIGN_LEFT, LALIGN_RIGHT, and
          LALIGN_CENTER.

          Defaults to LALIGN_LEFT.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_VertAlignment (ULONG)
          The vertical alignment of the objects in this layout group.
          Possible values are LALIGN_TOP, LALIGN_BOTTOM, and
          LALIGN_CENTER.

          Defaults to LALIGN_TOP.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_ShrinkWrap (BOOL)
          If set to TRUE, the layout group will shrink the interspacing
          of the child objects to minimum. Normally all extra space (if
          the total maximum size of the child objects is less than the
          size of the layoutgroup) is evenly distributed between the
          gadgets.

          Defaults to FALSE.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_EvenSize (BOOL)
          If TRUE, the layout group will try to reserve enough space to
          make the minimum size of each child object equal to the minimum
          of the largest child. Using this attribute makes it possible to
          have neatly arranged horizontal rows or grids of gadgets. This
          can take quite a bit of room, however, depending on the gadgets.

          Defaults to FALSE.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_SpaceInner (BOOL)
         Should layout leave space between objects or not. Set to FALSE
         if objects in a group should be put immediately beside each
         other.

         Defaults to TRUE.

         Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_SpaceOuter (BOOL)
         Should layout leave space around the group's objects or not.
         Set to TRUE if the objects should not be laid out using the
         whole group container box (for example if the group has a
         bevel around it).

         Defaults to FALSE.

         Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_InnerSpacing (ULONG)
          The minimum space left between objects. The value is in "virtual
          pixels", ie absolute pixels assuming bevel is configured for
          thin lines. If bevel configuration is something else, the value
          will be adjusted accordingly.

          Please avoid using this tag, if you do not require absolute
          control over the spacing. The LAYOUT_SpaceInner boolean is
          provided to tell whether there should be spacing or whether
          objects should be immediately connected to each other.

          Defaults to INTERSPACING.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_TopSpacing
      LAYOUT_BottomSpacing
      LAYOUT_LeftSpacing
      LAYOUT_RightSpacing (ULONG)
          The minimum space left to the top, bottom, left and right of
          the group, respectively. This value is in "virtual pixels", see
          LAYOUT_Spacing above.

          Please avoid using this tag, if you do not require absolute
          control over the spacing. The LAYOUT_SpaceOuter boolean is
          provided to tell whether there should be spacing or whether
          objects should be immediately connected to each other.

          If you use one of these tags to override a LAYOUT_SpaceOuter,
          pass this tag AFTER the LAYOUT_SpaceOuter tag.

          Defaults to 0.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_BevelStyle (ULONG)
          The style of the bevel drawn around the group. This value is
          passed to bevel.image.

          Defaults to BVS_NONE.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_BevelState (ULONG)
          The state of the bevel drawn around the group. Used to
          drawimagestate() the bevel.image.

          Defaults to IDS_NORMAL.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      LAYOUT_Label (STRPTR)
          The label drawn in the group bevel. This value is passed to
          bevel.image. Note that if LAYOUT_BevelStyle is set to BVS_NONE,
          no bevel will be rendered, and thus this label will not be used
          either.

          No default (bevel.image default used)

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_LabelImage (Object *)
          The BOOPSI image to use as the group bevel label. Passed to
          bevel.image.

          See LAYOUT_Label.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_LabelPlace (ULONG)
          The position of the label (See LAYOUT_Label).

          Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET)

      LAYOUT_RemoveChild (Object *)
          Pointer to an object you wish to remove from the layout
          hierarchy. The object will be disposed of, so after using this
          tag, the pointer will be invalid.

          Applicability is (OM_SET)

      LAYOUT_AddChild (Object *)
          Pointer to an object you wish to add to the list of gadgets for
          this layout hierarchy level.

          Applicability is (OM_NEW)

      LAYOUT_AddImage (Object *)
          Same as LAYOUT_AddChild, but will mark the object as an
          imageclass subclass (meaning that IM_DRAW will be used instead
          of GM_RENDER to display it, and that none of the gadgetclass
          methods apply to it).

          Applicability is (OM_NEW)

      LAYOUT_ModifyChild (Object *)
          Inform layout gadget that the following child specific tags in
          the taglist apply to the specified object. LAYOUT_AddChild will
          do this automatically for new objects.

          Applicability is (OM_SET)

      LAYOUT_RelVerify (BOOL)
          When a gadget returns a code that normally makes Intuition send
          an IDCMP_GADGETUP message to the application, layout.gadget
          will send a notification message (OM_NOTIFY, IDCMP_IDCMPUPDATE)
          with the essential information of the gadgetup message. This is
          because in certain situations the IDCMP_GADGETUP message can
          not be sent (in particular, when tab cycling between gadgets).
          The notification will consist of GA_ID set to the ID of the
          gadget in question, this LAYOUT_RelVerify tag set to TRUE, and
          the LAYOUT_RelCode tag (below) set to the gadget's return code
          (IntuiMessage.Code field of the IDCMP_GADGETUP).

          Applicability is (OM_NOTIFY)

      LAYOUT_RelCode (UWORD)
          A copy of the IntuiMessage.Code field of the IDCMP_GADGETUP in
          question, sent via OM_NOTIFY (ie. received as OM_UPDATE or
          IDCMP_IDCMPUPDATE).

          Applicability is (OM_NOTIFY)

      LAYOUT_TabVerify (BOOL)
          If the gadget release was triggered by tab cycling, this
          attribute will be TRUE in the release verify IDCMPUPDATE. This
          lets you distinguish, for example, between pressing tab and
          enter in a string gadget.

          Applicability is (OM_NOTIFY)

      LAYOUT_RelAddress (struct gadget *)
          Address of the gadget that sent the gadgetup is provided in the
          gadgetup notification using this tag.

          Applicability is (OM_NOTIFY)

      LAYOUT_HelpHit (UWORD)
          When a gadget returns a hit for helptest, the return code, along

          with GA_ID, is notified using this tag.

          Applicability is (OM_NOTIFY)

      LAYOUT_Parent (Object *)
          Set automatically by layout.gadget for all child objects, this
          attribute points to the parent layout object. If NULL, the
          layout object is the window's topmost layout.
          When an object is added to the layout hierarchy, it will
          receive this tag in OM_SET. If you so wish, you may use this to
          let the gadget talk to its parent layout group.
          Any group gadget that should work with layout.gadget must
          support this attribute.

          Applicability is (OM_SET, OM_GET)

      LAYOUT_DeferLayout (BOOL)
          By setting this tag to TRUE in your window's top layout, you
          can defer the layout and refresh process off the input.device
          context to your application. This will make input.device more
          responsive, and drop the (possibly quite heavy) process of
          recalculating the display to normal application priority
          instead of the priority 20
          of input.device. input handling will be retained in input.device
          context, to keep the GUI responsive.
          If you use this tag, you must listen to LAYOUT_RequestLayout
          and LAYOUT_RequestRefresh notifications and process them in
          prompt manner, or your GUI will not display properly, if at all.

          Applicability is (OM_NEW, OM_SET)

      LAYOUT_RequestLayout (Object *)
          If the above LAYOUT_DeferLayout tag is set to TRUE, the gadget
          will defer GM_LAYOUT methods invoked by input.device and notify
          its IC target with this tag. You should be listening to it in
          your application IDCMP handler (IDCMP_IDCMPUPDATE) and calling
          rethinklayout with false for refresh flag when receiving one.

          Defaults to FALSE.

          Applicability is (OM_NOTIFY)

      LAYOUT_RequestRefresh (Object *)
          If the above LAYOUT_DeferLayout tag is set to TRUE, the gadget
          will defer GM_RENDER methods invoked by input.device and notify
          its IC target with this tag. You should be listening to it in
          your application IDCMP handler (IDCMP_IDCMPUPDATE) and calling
          refreshglist when receiving one.

          Defaults to FALSE.

          Applicability is (OM_NOTIFY)

      LAYOUT_TextPen (WORD)
          The pen that will be used for group label text. See bevel.image.

          Applicability is (OM_NEW)

      LAYOUT_FillPen (WORD)
          The pen that will be used for the group fill pattern. See
          bevel.image.

          Applicability is (OM_NEW)

      LAYOUT_FillPattern (UWORD *)
          The fill pattern for the group. See bevel.image.

          Defaults to none.

          Applicability is (OM_NEW)

      GA_BackFill (struct hook *)
          A layer backfill hook to use in the group to provide a more
          complex background pattern.

          Defaults to clear for the main layout, and none for sublayouts.

          Applicability is (OM_NEW)

      LAYOUT_LabelColumn (ULONG)
          The side where the on which side of the gadget the label will
          be placed in the group. Valid values are PLACETEXT_LEFT and
          PLACETEXT_RIGHT. See CHILD_Label.

          Defaults to PLACETEXT_LEFT.

          Applicability is (OM_NEW, OM_SET, OM_NOTIFY)

      LAYOUT_LabelWidth (ULONG)
          The width of the label column in a vertical group. This attribute
          may be used to justify several layout groups.

          Applicability is (OM_SET, OM_GET)

      LAYOUT_AlignLabels (Object *)
          A pointer to another layout instance that should have equal
          label width with this one. Set to a cycle between all the
          groups, these will automatically justify their labels with each
          other. This attribute should be set as soon as possible, ie. in
          OM_NEW or OM_SET directly afterwards, before the layout size is
          calculated.

          Applicability is (OM_NEW, OM_SET)

      LAYOUT_Inversed (BOOL) (V42.27)
          Causes children to be added to the layout group via
          addhead() vs addtail().

          Applicability is (OM_NET, OM_SET)


      Attributes referring to the "current" child object:

      CHILD_MinWidth, CHILD_MinHeight (ULONG)
          The minimum width and height of the object, in pixels. Setting
          this attribute means that GM_DOMAIN is not respected in that
          direction.

          Defaults to ~0, which means that the layout gadget will ask the
          object, using GM_DOMAIN.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      CHILD_MaxWidth, CHILD_MaxHeight (ULONG)
          As above, for the maximum size.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      CHILD_NominalSize (BOOL)
          If this attribute is TRUE, layout will use GDOMAIN_NOMINAL
          instead of GDOMAIN_MINIMUM when requesting the minimum size of
          the gadget. This is useful when the minimum size of a gadget
          looks unattractive, but the gadget will return a more attractive
          size with GDOMAIN_NOMINAL.

          Defaults to FALSE.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      CHILD_WeightedWidth (ULONG)
          The relative width of the child object. See the DESCRIPTION
          above for the layout method. If set to 0, the child will always
          be rendered in the minimum size (specified by either GM_DOMAIN
          or CHILD_MinWidth). Use CHILD_MinWidth and a weighted with of 0
          instead of CHILD_MinWidth and CHILD_MaxWidth. The latter method
          will also work, but will slow down the layout. As a special
          rule, many BOOPSI images using bitmap data can not be resized
          from the initial size. Fix their size by setting MinWidth and
          MinHeight, and the weight to 0.

          Defaults to 100.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      CHILD_WeightedHeight (ULONG)
          The relative height of the child object. See CHILD_WeightedWidth.

          Applicability is (OM_NEW, OM_SET, OM_UPDATE)

      CHILD_WeightMinimum (BOOL)
          Setting this tag to TRUE will make the layout group set the
          weighted width and height to the minimum values set with
          CHILD_MinWidth and CHILD_MinHeight or returned by GM_DOMAIN. This
          allows creating layout groups where the relative size of the
          objects always remains the same. Be warned that if the object
          does not support GM_DOMAIN and minimum size is not set manually,
          the weight will be set to 2 (the default minimum size of an
          object). Normally you would want to set this tag for every
          resizable object in a layout group.

          Defaults to FALSE.

          Applicability is (OM_NEW)

      CHILD_ReplaceObject
          CHILD_ReplaceImage (Object *)
          Replace the current child object with the one specified. The
          current object will be disposed of. See LAYOUT_AddChild,
          LAYOUT_AddImage, LAYOUT_RemoveChild, LAYOUT_ModifyChild.

          Applicability is (OM_SET)

      CHILD_CacheDomain (BOOL)
          To speed up resizing, layout gadget will normally cache the
          first values returned by GM_DOMAIN and use that cache for
          subsequent relayouts, instead of calling GM_DOMAIN again.
          Normally this will have the same results all the time. If you
          have a custom gadget that might return varying values between
          calls to GM_DOMAIN (ie the minimum or maximum size of it could
          vary during runtime), set this tag to FALSE for that object and
          all its parent groups. Note that since layout groups are aware
          of their parent layouts, they can disable caching in the
          hierarchy above them automatically,  if you SetAttr this
          attribute _AFTER_ creating the whole layout hierarchy.

          Defaults to TRUE.

          Applicability is (OM_NEW, OM_SET) (OM_SET preferred)

      CHILD_Label (Object *)
          The imageclass object, preferably label.image, to use as the
          object's label. These labels are supported only left or right
          aligned groups, and will be placed in the left or right of the
          gadget even in horizontal groups. All the labels will take the
          space of the widest label. Label-less objects will be laid out
          in full width; if you want to leave the label column empty, use
          the special value LCLABEL_NOLABEL. Every object in a group gets
          the same amount of space reserved for a label, whether they have
          a label or not. This also (or in particular) applies to
          horizontal groups; usually the correct effect is reached by
          putting the label on the group itself instead of one of the
          objects in it. See LAYOUT_LabelColumn.

          Defaults to NULL.

          Applicability is (OM_NEW, OM_SET)

      CHILD_NoDispose (BOOL)
          By setting this attribute, you inform the layout object that
          this child object should not be automatically disposed when
          the layout object itself is disposed. This attribute allows
          sharing objects between layouts.

          Default is FALSE.

          Applicability is (OM_NEW, OM_SET)

      CHILD_ScaledWidth (UWORD) (V42.27)
          Scales the child minimum domain size to a larger value;

          minwidth = minwidth + ((minsize * scalewidth)/100)

          Default is 0.

          Applicability is (OM_NEW, OM_SET)

      CHILD_ScaledHeight (UWORD) (V42.27)
          Scales the child minimum domain size to a larger value;

          minheight = minheight + ((minsize * scaleheight)/100)

          Default is 0.

          Applicability is (OM_NEW, OM_SET)

  NOTES
      Setting the attributes via SetGadgetAttrs() (OM_SET) will not
      automatically rerender the display! Call rethinklayout() to
      relayout and refresh display after SetGadgetAttrs().

      In this document, the terms layout, group, and object are used
      intermixed. Most of the time, layout and group are used as
      synonyms. Virtually any object referred to could also be a
      layout group.

      To make defining layout hierarchies easier, the reaction_macros.h
      include file defines a set of macros that hide newobject()
      calls. This will clean up the rather large tag lists for the
      creation of layout groups. See the ReAction examples for use of
      these macros, and layout.gadget in general.

      In relation to above, remember that in AmigaOS (as of V40), the
      stack size is restricted. During the beta test period, the
      average size of a layout group for a whole window seemed to
      average at approximately 1 KB. Building as large tag lists as
      this on stack is rather slow, as well as easily overflowing the
      small default stacks of AmigaOS. For windows with relatively
      static layouts that are opened often, consider building tag
      lists as static data and passing a pointer to them for
      NewObjectA(). If this is too much work, make sure that your
      program's stack is large enough to hold  the tag list. If it is
      too small, you can use the V37 Exec stackswap() call to replace
      it with a larger one, or simply set the global variable long
      __stack to a large enough value, if the startup code you link
      with provides stack swap support, as for example the c.o of
      SAS/C 5.x and above does.

      Due to Intuition limitations, IDCMP_GADGETUP messages are not
      fully supported. The IAddress will always point to the root
      layout object of the window, not the actual gadget the message
      originates from. Use GadgetID to distinguish between gadgets.
      When using tab cycle, GADGETUP messages will be lost
      altogether. However, layout.gadget sends a notification for all
      gadgetups, containing the tags GA_ID, LAYOUT_RelVerify and
      LAYOUT_RelCode, containing, respectively, the ID, TRUE, and the
      IntuiMessage.Code value it returned. Additionally a
      LAYOUT_TabVerify tag will be TRUE or FALSE depending on whether
      the gadget release was triggered by tab cycle.
      Use of models and/or IDCMP_IDCMPUPDATE is encouraged.

  SEE ALSO
      ReAction example source for usage.