Description

• id - an optional ChipsId structure containing values to modify the currency state for the command
• cols - the number of columns of plots
• rows - the number of rows of plots
• xgap - spacing between the columns of plots as percentage of the frame width
• ygap - spacing between the rows of plots as percentage of the frame width
• usage - the behavior with regards to plots: 0 = use only existing plots (default); 1 = use existing plots, add new ones as needed; 2 = always create new plots; 3 = use only existing plots, excluding those listed; 4 = exclude the listed plots, add new ones as needed.
• plots - an optional list plot ids to include or exclude from the grid.

The grid_objects command creates a grid of NxM (rows x cols) plot areas. The plot areas are numbered sequentially from the upper left corner, left to right and top to bottom.

There are also individual commands for creating a row or a column of plots:

row_grid_objects([id,] cols_array, xgap, ygap [,usage [,plots]])
col_grid_objects([id,] rows_array, xgap, ygap [,usage [,plots]])

The cols_array is the number of columns of plots for each row; the number of elements in the array indicates the total number of rows. The rows_array is the number of rows of plots to use for each column; the number of elements in the array indicates the total number of columns. All other parameters are the same as for grid_objects.

If more than one frame is current, the gridding is applied to all the current frames.

The xgap and ygap values are given as a percentage of the plot area, as defined by the plot margins in the preferences file.

Usage Options

The usage parameter determines what plots are used in the grid. There are five allowed values:

• 0 = use only existing plots (default). Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, the remaining sections of the grid are empty. An optional list of plot ids to use in the grid may be supplied in the "plots" parameter.
• 1 = use existing plots, add new ones as needed. Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, new plot areas are created to fille the remaining sections of the grid. An optional list of plot ids to use in the grid may be supplied in the "plots" parameter.
• 2 = always create new plots. All new plots are created to fill the NxM grid.
• 3 = use only existing plots, excluding those listed. Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, the remaining sections of the grid are empty. A list of plot ids to be excluded from the grid is supplied in the "plots" parameter. If "plots" is empty, all existing plots are excluded from the grid.
• 4 = exclude the listed plots, add new ones as needed. Existing plots are arranged into an NxM grid. If fewer plot areas exist than are required, new plot areas are created to fille the remaining sections of the grid. A list of plot ids to be excluded from the grid is supplied in the "plots" parameter. If "plots" is empty, all existing plots are excluded from the grid.

In all cases, existing plots not included in the grid are hidden, not deleted. The plots may be redisplayed with another grid_objects call that include the plot, or by changing the plot location with reposition_plot ("ahelp py.chips reposition_plot") . Hidden plots may still be modified or deleted.

Customizing the Grid

To modify the gap spacing after the grid has been created, use the adjust_grid_gaps, adjust_grid_xgap, and adjust_grid_xgap commands ("ahelp py.chips adjust_grid_gaps") . The row widths and column heights can be changed with the following commands, each of which has a help file: adjust_grid_xrelsize, adjust_grid_xrelsizes, adjust_grid_xrelsize, and adjust_grid_xrelsizes.