XPCE Reference Manual: Section 1.156

1.156 class table

Class table is a subclass of class layout_manager, dealing with tabular layout of graphical objects. The functionality of this class is modelled after the HTML-3 definition of tables.

A number of classes are involved in the definition of a table:

Class table The layout manager that takes care of the overall control of the table.
Class device (or window) A table is a layout_manager, and requires a graphical device to manage. The first step in creating a table is to assign a table object to a device object using the method device->layout_manager.
Class table_slice, class table_row and class table_column The classes table_row and table_column are used by class table to build the grid as well as to store common row/column properties. They are normally created and managed by the table object. The user may wish to get a handle to them for deleting a row or column, or enumerating the cells in a row or column.
Class table_cell This is a subclass of class layout_interface, and deals with the interface between the layout_manager (the table) and the managed graphicals. See also graphical<-layout_interface.

1.156.1 Instance variables

table <- area: area

Occupied area on the layout_manager<-device. Includes the table<-frame and table<-rules. Updated by table->compute.

table <- cell_padding: size

Space around contents of the cell. The send-method table->cell_padding also accepts an integer, translating this into a size with equal width and height. See also table->cell_spacing, table->frame, table->border.

table <- cell_spacing: size

Space between the cells. Note that by setting this to minus the table<-border, the borders of adjecent cells will overlap, resulting in single lines between the cells. See also table->cell_padding, table->rules, table->frame and table->border.

table-changed: bool

A change has been made affecting the layout, so table->compute will recompute the layout of the table.

table <- columns: vector

Return the vector holdin all table_column objects. May be used to enumerate the defined columns.

Please note that this vector always exist, but may not contain the actual columns. Appended cells are stored in the table<-rows, and the column information is updated by table->compute.

table <-> current: point

Current table->append location. Used to fill a table left-to-right, row-by-row. See table->append and table->next_row. May also be set explicitely, for example to modify the contents of a row with a sequence of table->append messages.

table <- frame: {void,above,below,hsides,vsides,box}

Parts of the frame painted. The definition is according to the HTML 3 proposal:

void: Don't draw the frame
above: Just draw a single line above the table
below: Just draw a single line below the table
hsides: above and below combined
vsides: Draw vertical lines left and right of the table
box: Draw a box around the table.
See also table->rules, controlling the lines around the individual cells.

table <- rows: vector

Return the vector object holding the table_row objects. May be used to enumerate the rows. Do not modify the contents of this vector directly. See also table<-row and table<-columns.

table <- rules: {none,groups,rows,cols,all}

Rules painted around cells:

none: Do not paint any lines around the cells
groups: Draw a line below/right of each table<-column or table<-row that has table_slice->end_group.
rows: Draw a line between each row.
cols: Draw a line between each column
all: Put each cell in a box.
Note that table->frame controlls the lines around the entire table object.

1.156.2 Send methods

table ->append: cell=table_cell, x=[int], y=[int]

Append a cell at the given location. A default x or y is read from the table<-current attribute. Please note that table_cell<-convert wraps graphical objects into a table cell, so graphicals can be appended directly to the table.

After the table->append, table<-current is incremented to the next column on this row. If there is no next column, it will be created using table<-column. Use table->next_row to force the insertion point to the first column on the next row.

If the next column on this row points into a row-spanned cell, the insertion point will be incremented to point to the first free column after this row-spanned cell.

table ->border: 0..

Thickness of border-lines. Which lines are painted is controlled by table->rules and table->frame.

table ->compute:

Compute column and row dimensions, places the graphicals in the cells and updates the table<-area. Invoked by device->compute of the layout_manager<-device I'm associated with.

table ->compute_bounding_box:

Compute the bounding box. Called by the layout_manager<-device to set the bounding box of the layout_manager<-device (to the table<-area of the table object).

table ->delete: what=table_cell|table_row|table_column, keep=[bool]

Delete a cell, row or column. These objects are fetched using table<-cell, table<-row or table<-column. Deleting rows or columns holding spanned cells will deal naturally with these cells: There location and spanning will be updated such that they span the same set of rows/columns.

If keep is @on, the content of the row, column or cell are kept. Otherwise the content is visual->destroyed.

If a column is deleted, all cells that will be deleted from the table are attached to the table_column object. Together with table->insert_column, this allows for relocating columns if a table without loosing the table-properties. Note that the column should be object->lock_object’ed to avoid destruction by the incremental garbage collector. The following code moves column 4 to be the first column:

...
get(Table, column, 4, Col),
send(Col, lock_object, @on),
send(Tbale, delete, Col, @on),
send(Table, insert_column, 1, Col),
send(Col, lock_object, @off),
...

table ->delete_rows: from=[int], to=[int], keep=[bool]

Delete a rows from the table. From defaults to the first row and to to the last one. If keep is @on the graphicals are not deleted from the device. By default they are deleted using visual->destroy.

table ->initialise:

Creates an empty table. Normally, a table is immediately associated to a device object:

...
new(D, device),
send(D, layout_manager, new(T, table)),
...

Next, columns may be specified using table<-column, and/or the table may be filled using table->append. Note that explicit definition of columns is not required.

table ->insert_column: at=int, new=table_column

Insert new column at the specified index. All columns at or to the right of this column will be moved 1 position to the right. If the column is inserted in a spanned cell, the spanning of this cell is increased by one. See also table->insert_row and table->delete.

table ->insert_row: at=int, row=[table_row]

Insert new row at the specified index. Rows with this or greater index will be moved down. Cells spanning this row will have their table_cell<-row_span incremented. See also table->insert_column and table->delete.

table ->next_row: end_group=[bool]

Modifies table<-current to point to the first column of the next row. Used together with table->append to fill the table left-to-right, row-by-row.

table ->place_cells:

Called by table->compute to deal with the actual placement of the graphicals in the cells.

table ->selection: table_cell|chain*

Specify the selected cell or cells. There is yet no possibility to select a row or column as a unit.

Please note that selecting a table_cell object is different from selecting the graphical image of the cell in the associated layout_manager<-device.

1.156.3 Get methods

table <-cell: x=int|name, y=int|name -> table_cell

Fetch the table_cell object at the given column/row coordinate. Cordinates are 1-based. Fails silently if the table has no cell at the given coordinate. See also table<-row, table<-column, table->append.

table <-cell_from_position: at=point|event, allow_border=[bool] -> table_cell|point

Translate coordinate to cell or point. If the table contains a cell at the given location, this cell will be returned. Otherwise, if the location is within the column/row range of the table, a point will be returned containing the coordinates of the (empty) cell. This may be used to create a cell at the indicated location. For example:

start_typing(Table, Ev:event) :->
        get(Table, cell_from_position, Ev, CellOrPos),
        (   send(CellOrPos, instance_of, table_cell)
        ->  send(CellOrPos?image, keyboard_focus, @on)
        ;   object(CellOrPos, point(X, Y)),
                send(Table, append,
                     new(T, editable_text('')), X, Y),
                send(Table, compute), % force display now
                send(T, keyboard_focus, @on)
        ).

table <-cells_in_region: area -> chain

Find all cells in a row/column region. Handy for operations on a rectangular subpart of the table. See also table<-cell, table<-row or table<-column.

table <-column: x=int|name, create=[bool] -> table_column

Fetch the table_column object at the given 1-based column index or with the given name. If Create is @on, a new column is created and attached to the table if the specified n-th column is not yet defined.

Normally used to specify the column attributes:

...,
get(Table, column, 1, @on, Col),
send(Col, halign, center),
...

Access to the table_column object is can also used with table->delete to delete a column from the table.

table <-row: y=int|name, create=[bool] -> table_row

Fetch the table_row object at the given 1-based row index or with the given name. If Create is @on, a new row is created and attached to the table if the specified n-th row is not yet defined.

Normally used to specify the row attributes:

...,
get(Table, row 1, @on, Col),
send(Col, valign, center),
...

Access to the table_row object is can also used with table->delete to delete a row from the table.