Nicola Pero (n.pero@mi.flashnet.it)
The GSHbox class (a GNU extension)

Copyright: (C) 1999-2010 Free Software Foundation, Inc.


GSHbox inherits from GSTable the autosizing/autoresizing engine. The only real difference between a GSHbox and a GSTable with 1 row is that the GSHbox has a much simpler, easier and friendlier API.

You shouldn't use GSTable methods with GSHbox (exception: methods explicitly quoted in comments to this file as 'inherited from GSTable'). If you need to do that, you should be using GSTable instead.

A GSHbox is an invisible view (a logical device) which can contain some views. The GSHbox controls the position and sizes of these views so that they are lined up in a row.

To initialize a GSHbox, you should always use -init method. Don't use GSTable methods. The correct way to start using a new GSHbox is simply:

  hbox = [GSHbox new];

(well, of course, autoreleasing it if necessary). You add a view to a GSHbox using the method -addView: and its variants. The views you add to a GSHbox are placed by the GSHbox in its subview hierarchy, and moved (and/or resized in the vertical direction) so that they are positioned one after the other, from left to right, in a row. Before adding views to a box, you should resize them to the least comfortable size you want them to have. The GSHbox considers this size as the minimum size your view should ever have, and never resizes your view below this size.

The initial size of the GSHbox is zero; each time you add a view in the GSHbox, the GSHbox resizes itself to fit the new contents. Usually, you simply add objects to the GSHbox, and let it compute its size (this is the minimum size); you may get this resulting size by

  size = [yourHBox size];

for example, if the GSHbox is to be used as the content view of a window, you may create the window exactly with this size.

You should never force a GSHbox in a size different from the one it has automatically computed. It sounds quite pointless anyway. The only correct (and meaningful) way to resize a GSHbox is through -resizeWithOldSuperviewSize: messages (in the view hierarchy). In other words, after you place your box in the view hierarchy, then you may resize the superview and (if the superview has autoresizing of subviews enabled) your box is resized automatically accordingly.

By default, there is no space between the added views. By using the method -addView:withMinXMargin: you may tell the GSHbox to insert some space (a margin) between the view you are adding and the previous one (the one at its left).

If what you want is space around the GSHbox, and not between views in the GSHbox, you don't want a margin but a border; you should then use -setBorder: , which will add an equal amount of space on all the sides of the box. You can also set a different border on each side (see -setMinXBorder: and similar methods).

A useful feature of GSHbox is that it supports separators. This facility is not directly available in GSTable (to add separators to a GSTable you need to create and handle them yourself). A GSHbox separator is a vertical groove line, used to mark the separation between different elements of a box. To add a separator, simply invoke the method -addSeparator . The separator is put at the right of the last added view.

To use GSHbox proficiently, it is crucial to set correctly the autoresizing mask of each view before adding it to the GSHbox.

The GSHbox treats each view and its margins as a whole (see the GSTable class description for more information).

When the GSHbox is resized in the vertical direction (as a consequence of user intervertion, for example), what happens is:

When the GSHbox is resized in the horizontal direction, its behaviour is as follows:

GSHbox : GSTable

Declared in:
Availability: OpenStep

Description forthcoming.

Instance Variables

Method summary


- (void) addSeparator;
Availability: OpenStep

Add a separator with the default MinXMargin.


- (void) addSeparatorWithMinXMargin: (float)aMargin;
Availability: OpenStep

Add a separator (a vertical groove line encompassing all the height of the GSHbox) to the GSHbox, inserting a margin aMargin between the separator and the last added view.


- (void) addView: (NSView*)aView;
Availability: OpenStep

addView: enablingXResizing: 

- (void) addView: (NSView*)aView enablingXResizing: (BOOL)aFlag;
Availability: OpenStep

addView: enablingXResizing: withMinXMargin: 

- (void) addView: (NSView*)aView enablingXResizing: (BOOL)aFlag withMinXMargin: (float)aMargin;
Availability: OpenStep

Pack views in the GSHbox. Don't use the corresponding methods of GSTable, which are far more general and far more complicate. If you need to do that, use GSTable instead.

Add a view to the box, enabling X Resizing only if flag is YES, and a MinXMargin aMargin. If aFlag is YES the [view and its margins] should be resized in the horizontal direction when the GSHbox is resized in the horizontal direction. If aFlag is NO the view is never X-resized and always left in its original width. The default is YES.

The min X margin is used to separate the view from the preceding one. The first view added to the box has no min X margin; if you try setting one for it, it is ignored (zero is used instead).

When views are added to the GSHbox, it might happen that some of the added views have a greater height than others. When this happens, the GSHbox resizes all the views to the highest height. As usual, each view is resized with its margins; the effect of the resizing on each view is determined by the autoresizing mask of the view. The classical options are

(NSViewMinYMargin | NSViewMaxYMargin)
Center the view vertically
Flush the view up (down if the GSHbox is flipped)
Flush the view down (up if the GSHbox is flipped)
Expand the view to the whole height

(you may need to OR these masks with the mask you use in the horizontal direction, if you use any).

With a GSHbox, only one margin is set when you add views to the GSHbox: the margin between each view and the preceding one. Exception: the first view is special, and has no margin set (it has no preceding view to be separated from). Space above or below the view may result if the view is shorter, in the vertical direction, than the other views in the GSHbox; in that case the view is resized to fit vertically, according to its autoresizingMask. By changing the autoresizingMask you may decide whether the space should go to the view or to its vertical margins; this for example lets you center vertically or flush up/down your view.

addView: withMinXMargin: 

- (void) addView: (NSView*)aView withMinXMargin: (float)aMargin;
Availability: OpenStep


- (id) init;
Availability: OpenStep

Always use init for GSHbox: other methods don't make sense. Don't used GSTable methods. You do not need to specify the number of views you plan to put in the box when you initialize it.


- (int) numberOfViews;
Availability: OpenStep

Return the number of views in the GSHbox (separators included).


- (void) setDefaultMinXMargin: (float)aMargin;
Availability: OpenStep

Use only the following method to set a default margin. The default margin set with the following method will be used for all the views added after. (Exception: the first view put in the box has no margins at all) It will not affect already added views. In a GSHbox, only one margin is used, the one between each view and the preceding one. If what you want is space around the GSHbox, you don't want a margin but a border; use setBorder: (see GSTable, "Setting Border"). If you need more complicated margins/borders, use GSTable.

Instance Variables for GSHbox Class


@protected float _defaultMinXMargin;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.


@protected BOOL _haveViews;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.