layout.gadget

ActivateLayoutGadget	FlushLayoutDomainCache	LAYOUT_GetClass	LayoutLimits	RethinkLayout
PAGE_GetClass	RefreshPageGadget	SetPageGadgetAttrsA

gadgetclass

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. Subtract 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.
  
  

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 (this method is recursive).

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.

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

GA_TextAttr (struct TextAttr *)

The font that will be used for the group label.

Defaults to NULL (RastPort default font).

Applicability is (OM_NEW)

GA_ReadOnly (BOOL)

Sets the layout object to readonly, input is ignored and blocked from reaching all children.

Applicability is (OM_NEW, OM_SET)

GA_Disabled (BOOL)

Sets the layout object to disabled state. This tag is propagated down to all children.

Applicability is (OM_NEW, OM_SET)

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

see next

LAYOUT_BottomSpacing

see next

LAYOUT_LeftSpacing

see next

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.

NOTE:

bevel.image does not yet implement this feature so

this tag currently does nothing.

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.

OM_SET was not supported at all until V47. NOTE: If using OM_SET, you *MUST* call through SetGadgetAttrs() to protect the window layout properly.

(On OS4, you should use the LM_ADDCHILD method instead.)

Applicability is (OM_NEW, OM_SET)

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).

OM_SET was not supported at all until V47. NOTE: If using OM_SET, you *MUST* call through SetGadgetAttrs() to protect the window layout properly.

(On OS4, you should use the LM_ADDIMAGE method instead.)

Applicability is (OM_NEW, OM_SET)

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.

NOTE:

You *MUST* call through SetGadgetAttrs() to protect the

window layout properly.

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_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 *)

(V44) see next

CLASSACT_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)

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_Inverted (BOOL) (V42.27) - Causes children to be added to the layout group via

LAYOUT_WeightBar (BOOL) (V43.1) - Place a user adjustable weighting bar here

LAYOUT_NoLayout (BOOL) (V45) - Do not layout the children. All children must have valid

Attributes referring to the "current" child object:

CHILD_MinWidth

see next

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

see next

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

see next

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)

NOTE:

You *MUST* call through SetGadgetAttrs() to protect the

window layout properly.

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 in left or right aligned groups, and will be placed at 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)

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 classact.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 ClassAct 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.

ClassAct example source for usage, and window_cl.doc