home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / docs / groupclass.doc < prev    next >
Encoding:
Text File  |  1995-04-24  |  12.6 KB  |  328 lines
  1.  
  2.                File: groupclass.doc
  3.         Description: Groupclass documentation.
  4.           Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.                      (C) Copyright 1994-1995 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. groupclass/--background--
  13. groupclass/Methods
  14. groupclass/Attributes
  15.  
  16. groupclass/--background--                            groupclass/--background--
  17.  
  18.     NAME
  19.         Class:          groupclass
  20.         Superclass:     baseclass
  21.         Include File:   <libraries/bgui.h>
  22.  
  23.     FUNCTION
  24.         To layout it's members in a specific area.   A groupclass  object may
  25.         have any number of members which are layouted accoording  to a set of
  26.         layout attributes.
  27.  
  28.         The number of members a group can have is only limited by  the amount
  29.         of available memory. This will allow for simple and extremely complex
  30.         layout's.
  31.  
  32. groupclass/Methods                                         groupclass/Methods
  33.  
  34.     NEW METHODS
  35.         GRM_ADDMEMBER -- This  method  can  be  used  to  add  a member to an
  36.                 existing group. This method uses the following custom message
  37.                 structure:
  38.  
  39.                 struct grmAddMember {
  40.                         ULONG           MethodID;    /* GRM_ADDMEMBER */
  41.                         Object         *grma_Member; /* Object to add. */
  42.                         ULONG           grma_Attr;
  43.                 };
  44.  
  45.                 grma_Attr -- This is an array of attributes which control the
  46.                         way the object is layouted.  The following attributes
  47.                         are possible:
  48.  
  49.                         LGO_FixWidth -- ti_Data contains the  width at  which
  50.                                 the object is fixed.
  51.  
  52.                         LGO_FixHeight -- ti_Data contains the height at which
  53.                                 the object is fixed.
  54.  
  55.                         LGO_Weight -- Scaling objects  is weight  controlled.
  56.                                 the default weight  an  object  get's  is 50.
  57.                                 This attribute  can  be  used to  change that
  58.                                 setting.
  59.  
  60.                         LGO_FixMinWidth -- The  object   is  fixed   at  it's
  61.                                 minimum width.
  62.  
  63.                         LGO_FixMinHeight -- The  object  is  fixed   at  it's
  64.                                 minimum height.
  65.  
  66.                         LGO_Align -- Normally  only  objects  in  a  vertical
  67.                                 group are aligned when they  have a  label on
  68.                                 the left side  of  their  hitbox.  When  this
  69.                                 attribute is TRUE the object will get aligned
  70.                                 wherever the label is placed.
  71.  
  72.                         LGO_NoAlign ** V38 ** -- Normally  all  objects  in a
  73.                                 vertical group with a label  on  the  left of
  74.                                 the hitbox are all aligned. This tag prevents
  75.                                 this.
  76.  
  77.                 Example:
  78.                         Object          *group, *cycle;
  79.  
  80.                         DoMethod( group, GRM_ADDMEMBER, cycle,
  81.                                   LGO_FixMinHeight, TRUE,
  82.                                   LGO_Weight,       DEFAULT_WEIGHT,
  83.                                   TAG_END );
  84.  
  85.                 This adds a cycle object to a group fixing the height to it's
  86.                 minimum size and the weight to 50.
  87.  
  88.                 Please note that the weight of an object  affects to  with of
  89.                 the object in a horizontal group and the height of the object
  90.                 in a vertical group.
  91.  
  92.                 This method may only be used when the  group  is _not_ active
  93.                 (I.E. displayed in a window).
  94.  
  95.                 Returns TRUE uppon success, FALSE uppon failure.
  96.  
  97.                 If this method was successfull you do not need to dispose  of
  98.                 the added member anymore. This will be disposed of as soon as
  99.                 the group to which the member was added is disposed of.
  100.  
  101.         GRM_REMMEMBER -- With  this method you  can remove  an object  from a
  102.                 group again. This method  uses the  following  custom message
  103.                 structure:
  104.  
  105.                 struct grmRemMeber {
  106.                         ULONG           MethodID;    /* GRM_REMMEMBER */
  107.                         Object         *grmr_Member; /* Object to remove. */
  108.                 };
  109.  
  110.                 This method may only be used when the  group  is _not_ active
  111.                 (I.E. displayed in a window).
  112.  
  113.                 Return code not defined.
  114.  
  115.                 You are responsible for disposing of the removed object.
  116.  
  117.         GRM_DIMENSIONS -- This method is sent to all members to inquire about
  118.                 their minimum sizes. Please refer to the  "methods.doc"  file
  119.                 for more information on this method.
  120.  
  121.         GRM_ADDSPACEMEMBER -- This method can be used to  add a  special kind
  122.                 of  object  to  the  group.   The  member  will  be  a weight
  123.                 controlled  spacing  in  the  group.   This  method  uses the
  124.                 following custom message structure:
  125.  
  126.                 struct grmAddSpaceMember {
  127.                         ULONG           MethodID;   /* GRM_ADDSPACEMEMBER */
  128.                         ULONG           grms_Weight;
  129.                 };
  130.  
  131.                 grms_Weight -- This  field  must  contain  the  weight of the
  132.                         spacing object.   Please refer  to the  GRM_ADDMEMBER
  133.                         section for more information about weights.
  134.  
  135.                 This method may only be used when the  group  is _not_ active
  136.                 (I.E. displayed in a window).
  137.  
  138.                 Returns TRUE uppon success, FALSE uppon failure.
  139.  
  140.         GRM_INSERTMEMBER --  This   method   is   basically   the   same   as
  141.                 GRM_ADDMEMBER with the exception that you can determine where
  142.                 the object is added.  This  method  uses the following custom
  143.                 message structure:
  144.  
  145.                 struct grmInsertMember {
  146.                         ULONG           MethodID;    /* GRM_INSERTMEMBER */
  147.                         Object         *grmi_Member; /* Object to add. */
  148.                         Object         *grmi_Pred;
  149.                         ULONG           grmi_Attr;
  150.                 };
  151.  
  152.                 grmi_Pred -- This must point to  the object  after  which the
  153.                         new member is inserted.  You may set this to  NULL in
  154.                         which case the new member is inserted at the start of
  155.                         the list.
  156.  
  157.                 grmi_Attr -- This is an array of attributes which control the
  158.                         way the object is layouted.   The  attributes allowed
  159.                         here are exactly the same as the  attributes  you can
  160.                         use with the GRM_ADDMEMBER method.
  161.  
  162.                 Example:
  163.                         Object          *group, *cycle, *button;
  164.  
  165.                         DoMethod( group, GRM_INSERTMEMBER, cycle, button,
  166.                                   LGO_FixMinHeight, TRUE,
  167.                                   LGO_Weight,       DEFAULT_WEIGHT,
  168.                                   TAG_END );
  169.  
  170.                 This adds a cycle object to a group fixing the height to it's
  171.                 minimum  size  and  the weight to 50.  The  cycle  object  is
  172.                 inserted after the button object.
  173.  
  174.                 Please note that the weight of an object  affects to  with of
  175.                 the object in a horizontal group and the height of the object
  176.                 in a vertical group.
  177.  
  178.                 This method may only be used when the  group  is _not_ active
  179.                 (I.E. displayed in a window).
  180.  
  181.                 Returns TRUE uppon success, FALSE uppon failure.
  182.  
  183.                 If this method was successfull you do not need to dispose  of
  184.                 the added member anymore. This will be disposed of as soon as
  185.                 the group to which the member was added is disposed of.
  186.  
  187.     CHANGED METHODS
  188.         OM_DISPOSE -- When this  method is called it will  also dispose of all
  189.                 objects that are added to the group.
  190.  
  191. groupclass/Attributes                                    groupclass/Attributes
  192.  
  193.     NAME
  194.         GROUP_Style -- ( ULONG )
  195.  
  196.     FUNCTION
  197.         Set  the  style  of  the  group  to  create.  The following styles are
  198.         possible:
  199.  
  200.         GRSTYLE_HORIZONTAL -- A horizontal group is created.
  201.  
  202.         GRSTYLE_VERTICAL -- A vertical group is created.
  203.  
  204.         Default is GRSTYLE_HORIZONTAL. Applicability is (I).
  205.  
  206.     NAME
  207.         GROUP_Spacing -- ( ULONG )
  208.  
  209.     FUNCTION
  210.         Set  the  number of pixels the group uses as a space between the group
  211.         members.
  212.  
  213.         Default is 0. Applicability is (I).
  214.  
  215.     NAME
  216.         GROUP_HorizOffset,         GROUP_VertOffset,         GROUP_LeftOffset,
  217.         GROUP_RightOffset, GROUP_TopOffset, GROUP_BottomOffset -- ( ULONG )
  218.  
  219.     FUNCTION
  220.         Set the offset in pixels from the group borders at which the layouting
  221.         is started. Please note that frames are not taken into consideration.
  222.  
  223.         Default is 0. Applicability is (I).
  224.  
  225.     NAME
  226.         GROUP_Member -- ( Object * )
  227.  
  228.     FUNCTION
  229.         To add a member to a group at initialization time.  This tag is read a
  230.         little different than the other tags.  Following  the object a  set of
  231.         layout attributes can be passed. Example:
  232.  
  233.         UBYTE           *labels[] = { "LAB1", "LAB2", NULL };
  234.         Object          *group, *cycle;
  235.  
  236.         /* With macros */
  237.         group = HGroupObject,
  238.                 StartMember,
  239.                         cycle = Cycle( "Cycle", labels, 0, 0 ),
  240.                         FixMinHeight, Weight( DEFAULT_WEIGHT ),
  241.                 EndMember,
  242.         EndObject;
  243.  
  244.         /* Without macros */
  245.         group = BGUI_NewObject( BGUI_GROUP_GADGET,
  246.                 GROUP_Member,
  247.                         cycle = BGUI_NewObject( BGUI_CYCLE_GADGET,
  248.                                 LAB_Label,      "Cycle",
  249.                                 CYC_Labels,     labels,
  250.                                 CYC_Active,     0,
  251.                                 GA_ID,          0,
  252.                                 TAG_END ), LGO_FixMinHeight, TRUE,
  253.                                            LGO_Weight, DEFAULT_WEIGHT,
  254.                                            TAG_END, 0,
  255.                 TAG_END );
  256.  
  257.         As you can see the layout attributes follow the object  pointer in the
  258.         ti_Data field directly. Therefore it is also important that the layout
  259.         attributes are terminated  with a  TAG_END, 0  rather  then  a  single
  260.         TAG_END. The macros will automatically do this for you.
  261.  
  262.         If by any chance the object you add is NULL. The creation of the group
  263.         will fail. All objects that where successfully added to the  group are
  264.         disposed of in this case.
  265.  
  266.         Default is NULL. Applicability is (I).
  267.  
  268.     SEE ALSO
  269.         Methods/GRM_ADDMEMBER
  270.  
  271.     NAME
  272.         GROUP_SpaceObject -- ( ULONG )
  273.  
  274.     FUNCTION
  275.         To add a weight controlled spacing member at create time.  The data of
  276.         this tag should contain the weight of the spacing.
  277.  
  278.         Default is 0. Applicability is (I).
  279.  
  280.     NAME
  281.         GROUP_BackFill -- ( ULONG )
  282.  
  283.     FUNCTION
  284.         To provide a backfill possibility the same as the frameclass supplies.
  285.         The  data  passed  with  this  tag  should  be the same as defined and
  286.         documented   for   the   FRM_BackFill   attribute  of  the  frameclass
  287.         documentation. Please note that this tag  is overided  when  the group
  288.         has a frame attached to it.
  289.  
  290.         Default is 0. Applicability is (I).
  291.  
  292.     SEE ALSO
  293.         frameclass.doc/FRM_BackFill
  294.  
  295.     NAME
  296.         GROUP_EqualWidth -- ( BOOL )
  297.  
  298.     FUNCTION
  299.         To force all members of the group to get the same minimum width.  This
  300.         makes it easy to create a row of objects which  all are  equally wide.
  301.  
  302.         Default is FALSE. Applicability is (I).
  303.  
  304.     SEE ALSO
  305.         GROUP_EqualHeight
  306.  
  307.     NAME
  308.         GROUP_EqualHeight -- ( BOOL )
  309.  
  310.     FUNCTION
  311.         To force all members of the group to get the same minimum height. This
  312.         makes it easy to create a row of objects which  all are  equally high.
  313.  
  314.         Default is FALSE. Applicability is (I).
  315.  
  316.     SEE ALSO
  317.         GROUP_EqualWidth
  318.  
  319.     NAME
  320.         GROUP_Inverted -- ( BOOL )
  321.  
  322.     FUNCTION
  323.         To force the members added at create time  to be  AddHead()'ed  to the
  324.         member  list  instead  of  AddTail()'ed.   This  is  necessary for the
  325.         assembly macros of the BGUI package.
  326.  
  327.         Default is FALSE. Applicability is (I).
  328.