Up

GSTable class documentation

Authors

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

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


Contents -

  1. GSTable
  2. Advanced Description of GSTable
  3. Setting Row and Column Expand Flag

GSTable

A GSTable object is used to control the disposition (position and size) of a group of NSViews. The GSTable object offers two main facilities to the programmer:

You create a GSTable instance with a certain number of rows and columns. The GSTable object itself is invisible; it is only a logical device used to specify the subview position. Then, you place one by one the views you want to control in the GSTable, by calling a method of the family -putView:atRow:column: . Before placing a view in the table, you should resize it to the minimum comfortable size you want it to have. The table then automatically places the views, organizing them in well-ordered columns and rows.

The initial size of the GSTable is zero; each time you put a view in the GSTable, the GSTable recomputes sizes and as a result resizes itself so that it exactly fits the views it contains. You should not force a GSTable in a size different from the one it has automatically computed. The only acceptable, reasonable and meaningful way of resizing a GSTable is through the appropriate [NSView -resizeWithOldSuperviewSize:] message when the GSTable is in the view hierarchy.

When you add a view, you may specify some particular margins to be used for that view. If nothing is specified, the view is added to the table with the margins of 0. You should think of each view and its margins as a whole. A position in the GSTable is free or filled with a view and its margins.

The GSTable itself knows what is the minimum size it needs to have in order to comfortably display the views it contains. You may get this size by calling the method -minimumSize . When first filled, the table has this minimum size. If in any moment you want the table to restore itself to this size, you should invoke the method -sizeToFit .

When the GSTable receives a [NSView -resizeWithOldSuperviewSize:] message, it automatically rearranges the views it contains:

Advanced Description of GSTable

We call any view which is added to the GSTable a prisoner. The purpose of the GSTable is to effectively manage its prisoners. To do so, the GSTable creates a special view, called a jail, for each prisoner. The jails are subviews of the GSTable; each prisoner, when added to the GSTable, is made a subview of its jail. The GSTable always moves and resizes directly the jails. The moving is automatically transmitted to the prisoners, which are subviews of the jails; the resizing is transmitted through the usual autoresizing machinery, because the jails always have autoresizing of subviews turned on. This works because if a prisoner sends to its superview an [NSView -frame] message, the frame of the jail (and not the frame of the GSTable) is returned, so that each prisoner will autoresize itself in its jail frame. Moreover, any prisoner, being a subview of its jail, is clipped in its jail frame. If a prisoner draws something out of its jail frame, the output is discarded by the usual subview/view clipping machinery. This prevents the prisoners from disturbing each other. The dimension of the jail is the dimension of the prisoner plus its margins. Since the GSTable manages directly the jails, each prisoner is managed together with its margins. When the jail is resized, the prisoner receives a [NSView -resizeWithOldSuperviewSize:] , which makes it resize itself and its margins in the new jail size, according to its autoresizingMask.

Setting Row and Column Expand Flag

When the GSTable is resized, the extra space is equally divided between the Rows and Columns which have the X (or Y) resizing enabled. The following methods let you enable/disable the X (or Y) resizing of each row and column in the GSTable. Note that when the GSTable is first created, all its columns and rows have by default resizing enabled. -setXResizingEnabled:forColumn: , -setYResizingEnabled:forRow: .

GSTable : NSView

Declared in:
GNUstepGUI/GSTable.h
Availability: OpenStep

Description forthcoming.

Instance Variables

Method summary

addColumn 

- (void) addColumn;
Availability: OpenStep

Add a column to the GSTable. The column is added void, with zero width and X Resizing enabled.

addRow 

- (void) addRow;
Availability: OpenStep

Add a row to the GSTable. The row is added void, with zero height and Y Resizing enabled.

init 

- (id) init;
Availability: OpenStep

Initialize with a default of 2 columns and 2 rows.

initWithNumberOfRows: numberOfColumns: 

- (id) initWithNumberOfRows: (int)rows numberOfColumns: (int)columns;
Availability: OpenStep

Initialize a GSTable with columns columns and rows rows. If columns or rows is negative or null, a warning is issued and a default of 2 is used instead.

isXResizingEnabledForColumn: 

- (BOOL) isXResizingEnabledForColumn: (int)aColumn;
Availability: OpenStep

Return whether X resizing is enabled for the column aColumn.

isYResizingEnabledForRow: 

- (BOOL) isYResizingEnabledForRow: (int)aRow;
Availability: OpenStep

Return whether Y resizing is enabled for the row aRow.

minimumSize 

- (NSSize) minimumSize;
Availability: OpenStep

This returns the minimum size the GSTable should be resized to. Trying to resize the GSTable below this size will only result in clipping (ie, making it disappear) part of the GSTable.

numberOfColumns 

- (int) numberOfColumns;
Availability: OpenStep

Return the number of columns in the GSTable.

numberOfRows 

- (int) numberOfRows;
Availability: OpenStep

Return the number of rows in the GSTable.

putView: atRow: column: 

- (void) putView: (NSView*)aView atRow: (int)row column: (int)column;
Availability: OpenStep

Put aView in the GSTable, in the specified row and column. Zero (0) margins are used. If the column column (or the row row}) is not enough big to fully display aView and its margins, the column (or the row) is resized (regardless of the fact that X or Y Resizing is Enabled or not). It is understood that this will affect each view (and its margins) in the column (or row) according to the autoresizing mask of each view.

putView: atRow: column: withMargins: 

- (void) putView: (NSView*)aView atRow: (int)row column: (int)column withMargins: (float)margins;
Availability: OpenStep

Put aView in the GSTable, using margins as margin in all directions: left, right, top, bottom.

putView: atRow: column: withMinXMargin: maxXMargin: minYMargin: maxYMargin: 

- (void) putView: (NSView*)aView atRow: (int)row column: (int)column withMinXMargin: (float)minXMargin maxXMargin: (float)maxXMargin minYMargin: (float)minYMargin maxYMargin: (float)maxYMargin;
Availability: OpenStep

Put aView in the GSTable, using the specified margins. The names for the margins are chosen as to be as close as possible to the autoresizingMask convention. The margins are to be interpreted as follows:

minXMargin
Left Margin
maxXMargin
Right Margin
minYMargin
Lower Margin (Upper if view is flipped)
maxYMargin
Upper Margin (Lower if view is flipped)

Each view which is added to the GSTable can have some margins set. The GSTable treats the view and its margins as a whole. They are given (as a whole) some space, which is reduced or increased (but only if X or Y Resizing is Enabled for the column or the row in which the view resides) when the GSTable is resized. When this happens, the space is added (or subtracted) to the view or to the margins according to the autoResizeMask of the view.


putView: atRow: column: withXMargins: yMargins: 

- (void) putView: (NSView*)aView atRow: (int)row column: (int)column withXMargins: (float)xMargins yMargins: (float)yMargins;
Availability: OpenStep

Put aView in the GSTable, using xMargins as the left and right margins, and yMargins as the top and bottom margins.

setBorder: 

- (void) setBorder: (float)aBorder;
Availability: OpenStep

Set the GSTable up, bottom, left and right borders to the same value aBorder. The GSTable is immediately updated. If aBorder is negative, the border is reset to the default, which is zero (0). The border is simply unfilled space; it is measured in the GSTable coordinate system.

setMaxXBorder: 

- (void) setMaxXBorder: (float)aBorder;
Availability: OpenStep

Same as setXBorder: but set only the right border.

setMaxYBorder: 

- (void) setMaxYBorder: (float)aBorder;
Availability: OpenStep

Same as setXBorder: but set only the upper border (lower if the GSTable is flipped).

setMinXBorder: 

- (void) setMinXBorder: (float)aBorder;
Availability: OpenStep

Same as setXBorder: but set only the left border.

setMinYBorder: 

- (void) setMinYBorder: (float)aBorder;
Availability: OpenStep

Same as setXBorder: but set only the lower border (upper if the GSTable is flipped).

setXBorder: 

- (void) setXBorder: (float)aBorder;
Availability: OpenStep

Set the GSTable left and right borders to aBorder. If aBorder is negative, the border is reset to zero. The GSTable is immediately updated.

setXResizingEnabled: forColumn: 

- (void) setXResizingEnabled: (BOOL)aFlag forColumn: (int)aColumn;
Availability: OpenStep

Enable/disable X Resizing for the column aColumn} according to aFlag. Note: at present, enabling/disabling X resizing after the table has been put in the view hierarchy is not supported.

setYBorder: 

- (void) setYBorder: (float)aBorder;
Availability: OpenStep

Same as setXBorder: but set the up and bottom borders.

setYResizingEnabled: forRow: 

- (void) setYResizingEnabled: (BOOL)aFlag forRow: (int)aRow;
Availability: OpenStep

Enable/disable Y Resizing for the row aRow according to aFlag. Note: at present, enabling/disabling Y resizing after the table has been put in the view hierarchy is not supported.

sizeToFit 

- (void) sizeToFit;
Availability: OpenStep

If for any reason you need the GSTable to be redrawn (with minimum size), invoke the following.



Instance Variables for GSTable Class

_columnDimension

@protected float* _columnDimension;
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.

_columnXOrigin

@protected float* _columnXOrigin;
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.

_expandColumn

@protected BOOL* _expandColumn;
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.

_expandRow

@protected BOOL* _expandRow;
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.

_expandingColumnNumber

@protected int _expandingColumnNumber;
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.

_expandingRowNumber

@protected int _expandingRowNumber;
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.

_havePrisoner

@protected BOOL* _havePrisoner;
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.

_jails

@protected NSView** _jails;
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.

_maxXBorder

@protected float _maxXBorder;
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.

_maxYBorder

@protected float _maxYBorder;
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.

_minColumnDimension

@protected float* _minColumnDimension;
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.

_minRowDimension

@protected float* _minRowDimension;
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.

_minXBorder

@protected float _minXBorder;
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.

_minYBorder

@protected float _minYBorder;
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.

_minimumSize

@protected NSSize _minimumSize;
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.

_numberOfColumns

@protected int _numberOfColumns;
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.

_numberOfRows

@protected int _numberOfRows;
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.

_rowDimension

@protected float* _rowDimension;
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.

_rowYOrigin

@protected float* _rowYOrigin;
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.





Up