GSTable class documentation

Authors

Nicola Pero (n.pero@mi.flashnet.it)

The GSTable class (a GNU extension)

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

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:

• with a GSTable object, you do not need to specify the exact position and size of each view. You only specify the logical position, relative to the other views in the table. The actual frame of each view is then computed by the GSTable at run time.
• when the GSTable is resized (for example, because the user has resized the window in which the GSTable is), the GSTable takes care of moving and resizing all its views automatically. This is done in much a advanced and customizable way than in the usual standard NSView's autoresizing mechanism.

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:

• If the new width or height is equal or less than the table's minimum width or height, the GSTable simply arranges its views in the initial position. In other words, the GSTable refuse to resize below its minimum width or height. If you do that, part of the GSTable is clipped.
• If the new width or height is bigger than the table's minimum width or height, the space in excess is equally distributed between the columns or rows which have X (or Y) resizing enabled. When a column or a row is resized, each view in the column or row is resized together with its margins. By setting the autoresizingMask of each view, you may decide how the resizing operation will act on that particular view and its margins. For example, setting the autoresizingMask to NSViewWidthSizable | NSViewHeightSizable will always leave the margins fixed to their initial dimensions, and expand/reduce only the view, in all directions. Setting the autoresizingMask to NSViewMinXMargin | NSViewMaxXMargin | NSViewSizable | NSViewHeightSizable will instead expand/reduce both the margins and the view in the horizontal direction, but leave the margins fixed and expand/reduce only the view in the vertical direction. Whatever the autoresizingMask and the amount of the resizing, views and margins are never resized below their minimum comfortable size, as explained above. For more information on the autoresizingMask, please refer to the description of the -setAutoresizingMask: method of the NSView class.

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

• -addColumn
• -addRow
• -init
• -initWithNumberOfRows:numberOfColumns:
• -isXResizingEnabledForColumn:
• -isYResizingEnabledForRow:
• -minimumSize
• -numberOfColumns
• -numberOfRows
• -putView:atRow:column:
• -putView:atRow:column:withMargins:
• -putView:atRow:column:withMinXMargin:maxXMargin:minYMargin:maxYMargin:
• -putView:atRow:column:withXMargins:yMargins:
• -setBorder:
• -setMaxXBorder:
• -setMaxYBorder:
• -setMinXBorder:
• -setMinYBorder:
• -setXBorder:
• -setXResizingEnabled:forColumn:
• -setYBorder:
• -setYResizingEnabled:forRow:
• -sizeToFit

_columnDimension

_columnXOrigin

_expandColumn

_expandRow

_expandingColumnNumber

_expandingRowNumber

_havePrisoner

_jails

_maxXBorder

_maxYBorder

_minColumnDimension

_minRowDimension

_minXBorder

_minYBorder

_minimumSize

_numberOfColumns

_numberOfRows

_rowDimension

_rowYOrigin