home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / dev / gui / mui / developer / autodocs / mui_group.doc < prev    next >
Text File  |  1994-08-08  |  11KB  |  400 lines
  1. TABLE OF CONTENTS
  2.  
  3. Group.mui/Group.mui
  4. Group.mui/MUIA_Group_ActivePage
  5. Group.mui/MUIA_Group_Child
  6. Group.mui/MUIA_Group_Columns
  7. Group.mui/MUIA_Group_Horiz
  8. Group.mui/MUIA_Group_HorizSpacing
  9. Group.mui/MUIA_Group_PageMode
  10. Group.mui/MUIA_Group_Rows
  11. Group.mui/MUIA_Group_SameHeight
  12. Group.mui/MUIA_Group_SameSize
  13. Group.mui/MUIA_Group_SameWidth
  14. Group.mui/MUIA_Group_Spacing
  15. Group.mui/MUIA_Group_VertSpacing
  16. Group.mui/Group.mui
  17.  
  18.     Group class is responsible for the complete layout
  19.     of a MUI window. A group may contain any number of
  20.     child objects, maybe buttons, cycle gadgets or
  21.     even other groups.
  22.  
  23.     Some attributes of group class define how the children
  24.     of a group are layouted. You can e.g. tell your group
  25.     to place its children horizontally (in a row) or
  26.     vertically (in a column). Since every MUI object knows
  27.     about its minimum and maximum dimensions, group class
  28.     has everything it needs to do that job.
  29.  
  30.     More sophisticated layout is possible by assigning
  31.     different weights to objects in a group or by
  32.     making a group two-dimensional.
  33.  
  34.     Beneath the layout issues, a group object passes
  35.     attributes and methods through to all of its
  36.     children. Thus, you can talk and listen to any
  37.     child of a group by talking and listening to the
  38.     group itself.
  39. Group.mui/MUIA_Group_ActivePage
  40.  
  41.     NAME
  42.     MUIA_Group_ActivePage -- (V5) [ISG], LONG
  43.  
  44.     SPECIAL INPUTS
  45.     MUIV_Group_ActivePage_First
  46.     MUIV_Group_ActivePage_Last
  47.     MUIV_Group_ActivePage_Prev
  48.     MUIV_Group_ActivePage_Next
  49.  
  50.     VERSION
  51.     Available since version 5 of "group.mui".
  52.  
  53.     FUNCTION
  54.     Set (or get) the active page of a page group.
  55.     Only this active page is displayed, all others
  56.     are hidden.
  57.  
  58.     The value may range from 0 (for the first child)
  59.     to numchildren-1 (for the last child). Children are
  60.     adressed in the order of creation:
  61.  
  62.     PageGroup,
  63.        Child, Page_0_Object,
  64.        Child, Page_1_Object,
  65.        Child, Page_2_Object,
  66.        Child, Page_3_Object,
  67.        End;
  68.  
  69.     Note: You may *never* supply an incorrect page value!
  70.  
  71.     SEE ALSO
  72.     MUIA_Group_PageMode
  73. Group.mui/MUIA_Group_Child
  74.  
  75.     NAME
  76.     MUIA_Group_Child -- (V4) [I..], Object *
  77.  
  78.     FUNCTION
  79.     You supply a pointer to a previously created MUI object
  80.     here. This object will be treated as child of the group,
  81.     the group is responsible for positioning the object.
  82.  
  83.     Of course you can specify any number of child objects,
  84.     limited only by available memory.
  85.  
  86.     Normally, the value for a MUIA_Group_Child tag is
  87.     a direct call to another MUI_NewObject(), children
  88.     are generated "on the fly".
  89.  
  90.     When a group is disposed, all of its children will also
  91.     get deleted. If you supply a NULL pointer as child,
  92.     the group object will fail and previously dispose all
  93.     valid children found in the taglist.
  94.  
  95.     This behaviour makes it possible to generate a complete
  96.     application within one single (but long) MUI_NewObject()
  97.     call. Error checking is not necessary since every error,
  98.     even if it occurs in a very deep nesting level, will
  99.     cause the complete call to fail without leaving back
  100.     any previously created object.
  101.  
  102.    EXAMPLES
  103.     Please have a look at some of the supplied example
  104.     programs.
  105.  
  106.    SEE ALSO
  107.     MUIA_Group_Horiz
  108. Group.mui/MUIA_Group_Columns
  109.  
  110.     NAME
  111.     MUIA_Group_Columns -- (V4) [IS.], LONG
  112.  
  113.     FUNCTION
  114.     Indicate number of columns in a two dimensional group.
  115.     If you use this tag, the total number of children must
  116.     be dividable by the number of columns.
  117.  
  118.     The children will be positioned in a two dimensional
  119.     array, e.g. allowing easy creation of button fields
  120.     (maybe for calculator).
  121.  
  122.     The children in your taglist are always read line 
  123.     by line.
  124.  
  125.     When MUI layouts two-dimensional groups, it does
  126.     actually two layout calculations, one for the rows
  127.     and one the columns. Parameters like weights and
  128.     dimensions are handled this way:
  129.  
  130.     - the minimum width of a column/row is the maximum
  131.       minimum width of all objects in this column/row.
  132.  
  133.     - the maximum width of a column/row is the minimum
  134.       maximum width of all objects in this column/row.
  135.  
  136.     - the weight of a column/row is the sum of all
  137.       objects in this column/row.
  138.  
  139.     Actually, there is no difference if you use
  140.     MUIA_Group_Columns or MUIA_Group_Rows.
  141.  
  142.     EXAMPLE
  143.  
  144.     /* group of labeled string gadgets */
  145.  
  146.     GroupObject,
  147.        MUIA_Group_Columns, 2,
  148.        MUIA_Group_Child  , label1,
  149.        MUIA_Group_Child  , string1,
  150.        MUIA_Group_Child  , label2,
  151.        MUIA_Group_Child  , string2,
  152.        MUIA_Group_Child  , label3,
  153.        MUIA_Group_Child  , string3,
  154.            ...
  155.        End;
  156.  
  157.     SEE ALSO
  158.     MUIA_Group_Rows, MUIA_Group_Horiz
  159. Group.mui/MUIA_Group_Horiz
  160.  
  161.     NAME
  162.     MUIA_Group_Horiz -- (V4) [I..], BOOL
  163.  
  164.     FUNCTION
  165.     Boolean value to indicate whether the objects in
  166.     this group shall be layouted horizontally or
  167.     vertically. Defaults to FALSE.
  168.  
  169.     This is the easy way of telling your group how
  170.     it has to look like. If you want two-dimensional
  171.     groups, you have to use MUIA_Group_Columns
  172.     or MUIA_Group_Rows.
  173.  
  174.     EXAMPLE
  175.     GroupObject,
  176.        MUIA_Group_Horiz, TRUE,
  177.        MUIA_Group_Child, obj1,
  178.        MUIA_Group_Child, obj2,
  179.        MUIA_Group_Child, obj3,
  180.        End;
  181.  
  182.     SEE ALSO
  183.     MUIA_Group_Columns, MUIA_Group_Rows, MUIA_Group_Child
  184. Group.mui/MUIA_Group_HorizSpacing
  185.  
  186.     NAME
  187.     MUIA_Group_HorizSpacing -- (V4) [IS.], LONG
  188.  
  189.     FUNCTION
  190.     Number of pixels to be inserted between horizontal
  191.     elements of a group.
  192.  
  193.     Please use this tag wisely, you will override the
  194.     user's prefered default setting!
  195.  
  196.     SEE ALSO
  197.     MUIA_Group_Spacing, MUIA_Group_VertSpacing
  198. Group.mui/MUIA_Group_PageMode
  199.  
  200.     NAME
  201.     MUIA_Group_PageMode -- (V5) [IS.], BOOL
  202.  
  203.     VERSION
  204.     Available since version 5 of "group.mui".
  205.  
  206.     FUNCTION
  207.     Settings this attribute to TRUE makes the current group a page
  208.     group. Page groups always display only one their children, which
  209.     one can be adjusted with the MUIA_Group_ActivePage attribute.
  210.  
  211.     Imagine you have a preferences window with several different
  212.     pages, e.g. the MUI preferences with object, frame, image,
  213.     font, screen, keyboard and system prefs. Instead of one
  214.     separate window for each group, you could put all pages into
  215.     one page group and have a cycle gadget for page switching.
  216.     This will make your program easier to use since the user
  217.     won't have to handle a lot of windows. However, he will not
  218.     be able to work with more than one page at the same time.
  219.  
  220.     Sizes are calculated as follows:
  221.  
  222.     The minimum width/height of a page group is the maximum
  223.     minimum width/height of all its children.
  224.  
  225.     The maximum width/height of a page group is the minimum
  226.     maximum width/height of all its children.
  227.  
  228.     When the maximum width/height of a child in a page group is
  229.     smaller than the minimum width/height of the page group
  230.     (since it contains another child with big minimum width/height),
  231.     the child be centered.
  232.  
  233.     Page groups are not limited in depth, children of a page
  234.     group may of course be other page groups.
  235.  
  236.     If you want to have a gadget only visible under certain
  237.     conditions, you could make a page group containing this
  238.     gadget and an empty rectangle object.
  239.  
  240.     If you want TAB cycling for the objects in a page group,
  241.     simply include all objects in the cycle chain (as if
  242.     they all were visible at the same time).
  243.  
  244.     EXAMPLE
  245.     demo program "Pages.c"
  246.  
  247.     SEE ALSO
  248.     MUIA_Group_ActivePage
  249. Group.mui/MUIA_Group_Rows
  250.  
  251.     NAME
  252.     MUIA_Group_Rows -- (V4) [IS.], LONG
  253.  
  254.     FUNCTION
  255.     Indicate number of rows in a two dimensional group.
  256.     If you use this tag, the total number of children must
  257.     be dividable by the number of rows.
  258.  
  259.     The children will be positioned in a two dimensional
  260.     array, e.g. allowing easy creation of button fields
  261.     (maybe for calculator).
  262.  
  263.     The children in your taglist are always read line
  264.     by line.
  265.  
  266.     When MUI layouts two-dimensional groups, it does
  267.     actually two layout calculations, one for the rows
  268.     and one the columns. Parameters like weights and
  269.     dimensions are handled this way:
  270.  
  271.     - the minimum width of a column/row is the maximum
  272.       minimum width of all objects in this column/row.
  273.  
  274.     - the maximum width of a column/row is the minimum
  275.       maximum width of all objects in this column/row.
  276.  
  277.     - the weight of a column/row is the sum of all
  278.       objects in this column/row.
  279.  
  280.     Actually, there is no difference if you use
  281.     MUIA_Group_Columns or MUIA_Group_Rows.
  282.  
  283.     SEE ALSO
  284.     MUIA_Group_Columns, MUIA_Group_Horiz
  285. Group.mui/MUIA_Group_SameHeight
  286.  
  287.     NAME
  288.     MUIA_Group_SameHeight -- (V4) [I..], BOOL
  289.  
  290.     FUNCTION
  291.     Boolean value to indicate that all children of this
  292.     group shall have the same height.
  293.  
  294.     BUGS
  295.     Up to version 5 of groupclass, using MUIA_Group_SameHeight
  296.     could make objects larger than their maximum height. This
  297.     has been fixed for version 6.
  298.  
  299.     SEE ALSO
  300.     MUIA_Group_SameSize, MUIA_Group_SameWidth
  301. Group.mui/MUIA_Group_SameSize
  302.  
  303.     NAME
  304.     MUIA_Group_SameSize -- (V4) [I..], BOOL
  305.  
  306.     FUNCTION
  307.     This is a shorthand for MUIA_Group_SameWidth and
  308.     MUIA_Group_SameHeight, it sets both of these
  309.     attributes at once.
  310.  
  311.     Using MUIA_Group_SameSize, you won't need to think
  312.     if your group is horizontal or vertical, both
  313.     cases are handled automatically.
  314.  
  315.     Forcing all objects of a group to be the same size
  316.     is e.g. useful for a row of buttons. It's visually
  317.     more attractive when these buttons have equal sizes
  318.     instead of being just as big as the text within.
  319.  
  320.     BUGS
  321.     Up to version 5 of groupclass, using MUIA_Group_SameSize
  322.     could make objects larger than their maximum size. This
  323.     has been fixed for version 6.
  324.  
  325.     EXAMPLE
  326.  
  327.     /* three buttons, same size */
  328.  
  329.     GroupObject,
  330.        MUIA_Group_Horiz   , TRUE,
  331.        MUIA_Group_SameSize, TRUE,
  332.        MUIA_Group_Child   , but1,
  333.        MUIA_Group_Child   , but2,
  334.        MUIA_Group_Child   , but3,
  335.        End;
  336.  
  337.     SEE ALSO
  338.     MUIA_Group_SameWidth, MUIA_Group_SameHeight
  339. Group.mui/MUIA_Group_SameWidth
  340.  
  341.     NAME
  342.     MUIA_Group_SameWidth -- (V4) [I..], BOOL
  343.  
  344.     FUNCTION
  345.     Boolean value to indicate that all children of this
  346.     group shall have the same width.
  347.  
  348.     BUGS
  349.     Up to version 5 of groupclass, using MUIA_Group_SameWidth
  350.     could make objects larger than their maximum width. This
  351.     has been fixed for version 6.
  352.  
  353.     SEE ALSO
  354.     MUIA_Group_SameSize, MUIA_Group_SameHeight
  355. Group.mui/MUIA_Group_Spacing
  356.  
  357.     NAME
  358.     MUIA_Group_Spacing -- (V4) [IS.], LONG
  359.  
  360.     FUNCTION
  361.     This is a shorthand for MUIA_Group_HorizSpacing and
  362.     MUIA_Group_VertSpacing, it sets both of these
  363.     attributes at once.
  364.  
  365.     Using MUIA_Group_Spacing, you won't need to think
  366.     if your group is horizontal or vertical, both
  367.     cases are handled automatically.
  368.  
  369.     Note that setting a spacing value for a group
  370.     overrides the user's default settings. Please
  371.     use it only if you have a good reason.
  372.  
  373.     EXAMPLE
  374.  
  375.     /* no space between obj1 and obj2: */
  376.  
  377.     GroupObject,
  378.        MUIA_Group_Horiz  , TRUE,
  379.        MUIA_Group_Spacing, 0,
  380.        MUIA_Group_Child  , obj1,
  381.        MUIA_Group_Child  , obj2,
  382.        End;
  383.  
  384.     SEE ALSO
  385.     MUIA_Group_HorizSpacing, MUIA_Group_VertSpacing
  386. Group.mui/MUIA_Group_VertSpacing
  387.  
  388.     NAME
  389.     MUIA_Group_VertSpacing -- (V4) [IS.], LONG
  390.  
  391.     FUNCTION
  392.     Number of pixels to be inserted between vertical
  393.     elements of a group.
  394.  
  395.     Please use this tag wisely, you will override the
  396.     user's prefered default setting!
  397.  
  398.     SEE ALSO
  399.     MUIA_Group_Spacing, MUIA_Group_HorizSpacing
  400.