Customizing the display layout

Display elements
Placement of display elements
Display layout option reference

It is possible to rearrange the aptitude package list by making suitable modifications to the configuration file.

Display elements

The layout is stored in the configuration group Aptitude::UI::Default-Package-View, and consists of a list of display elements:

Name Type {
  Row row;
  Column column;
  Width width;
  Height height;

  additional options...
};

This creates a display element named Name; the type of element created is determined by Type. The Row, Column, Width, and Height options must be present; they determine where the display element is placed. (see below for a detailed explanation of how display elements are arranged)

For examples of how to change the display layout, see the theme definitions in the file /usr/share/aptitude/aptitude-defaults.

The following types of display elements are available:

Description

This display element will contain the information area (typically a description of the currently selected package).

The option PopUpDownKey gives the name of a keyboard command which will cause the display element to be shown or hidden. For instance, setting this to ShowHideDescription will give the current display element the same behavior as the default information area. The option PopUpDownLinked gives the name of another display element; the current element will be shown or hidden whenever the other element is.

MainWidget

This is a placeholder for the main display element: typically this is the list of packages. A display layout must contain exactly one MainWidget element: no more, no less.

Static

A region of the screen which displays some text, possibly containing formatting codes as described in the section called “Customizing how packages are displayed”. The text to display can be given in the Columns option, or it can be stored in another configuration variable specified by the ColumnsCfg option. The color of the text is determined by the color named by the Color option.

Static items can be displayed and hidden in the same way as Description items, using the PopUpDownKey and PopUpDownLinked options.

Placement of display elements

The display elements are arranged in a table. The upper-left corner of an element is in the cell given by its Row and Column options (typically starting from row 0 and column 0, but this is not required). The width of an element in cells is given by its Width option, and its height is given by its Height option.

Once the display elements are arranged and have been given an initial amount of space on the screen, there is likely to be space left over. If there is extra vertical space, each row containing a display element whose RowExpand option is true will be allocated a share of the extra space; similarly, if there is extra horizontal space, each column containing a display element whose ColExpand option is true will be allocated a share of the extra space.

In the event that there is not enough space, every row and column whose widgets all have their RowShrink or ColShrink options set to true will be shrunk. If this is not enough, all rows and columns are shrunk to fit into the available space.

If a display element is not expanded, but its row or column is, its alignment is determined by the RowAlign and ColAlign options. Setting them to Left, Right, Top, Bottom, or Center will tell aptitude where to place the element within the row or column.

For instance, the following configuration group creates a static element named Header, which is three cells wide and will expand horizontally but not vertically. It has the same color as other header lines and uses the standard display format for header lines:

Header Static {
  Row 0;
  Column 0;
  Width 3;
  Height 1;

  ColExpand true;
  ColAlign Center;

  RowAlign Center;

  Color ScreenHeaderColor;
  ColumnsCfg HEADER;
};

Display layout option reference

The following options are available for display elements:

ColAlign alignment;

alignment must be either Left, Right, or Center. If the row containing the current display element is wider than the element itself and ColExpand is false, the element will be placed within the row according to the value of alignment.

If this option is not present, it defaults to Left.

ColExpand true|false;

If this option is set to true, the column containing this display element will be allocated a share of any extra horizontal space that is available.

If this option is not present, it defaults to false.

Color colorname;

This option applies to Static elements. colorname is the name of a color (for instance, ScreenStatusColor) which should be used as the default color for this display element.

If this option is not present, it defaults to DefaultWidgetBackground.

ColShrink true|false;

If this option is set to true on each element in a column and there is not enough horizontal space, the column will be shrunk as necessary to fit the available space. Note that a column may be shrunk even if ColShrink is false; it simply indicates that aptitude should try shrinking a particular column before shrinking other columns.

If this option is not present, it defaults to false.

Column column;

Specifies the leftmost column containing this display element.

Columns format;

This option applies to Static display elements for which the ColumnsCfg option is not set. It sets the displayed contents of the status item; it is a format string as described in the section called “Customizing how packages are displayed”.

ColumnsCfg HEADER|STATUS|name;

This option applies to Static display elements. It sets the display format of the current element to the value of another configuration variable: if it is HEADER or STATUS, the options Aptitude::UI::Package-Header-Format and Aptitude::UI::Package-Status-Format, repectively, are used; otherwise, the option name is used.

If this option is not present, the value of the Columns option is used to control the contents of the static item.

Height height;

Specifies the height of the current display element.

PopUpDownKey command;

This option applies to Description and Static display elements.

command is the name of a keyboard command (for instance, ShowHideDescription). When this key is pressed, the display element will be hidden if it is visible, and displayed if it is hidden.

PopUpDownLinked element;

This option applies to Description and Static display elements.

element is the name of a display element. When element is displayed, the current element will also be displayed; when element is hidden, the current element will also be hidden.

Row row;

Specifies the uppermost row containing this display element.

RowAlign alignment;

alignment must be either Top, Bottom, or Center. If the row containing the current display element is taller than the element itself and RowExpand is false, the element will be placed within the row according to the value of alignment.

If this option is not present, it defaults to Top.

RowExpand true|false;

If this option is set to true, the row containing this display element will be allocated a share of any extra vertical space that is available.

If this option is not present, it defaults to false.

RowShrink true|false;

If this option is set to true on each element in a row and there is not enough vertical space, the row will be shrunk as necessary to fit the available space. Note that a row may be shrunk even if RowShrink is false; it simply indicates that aptitude should try shrinking a particular row before shrinking other rows.

If this option is not present, it defaults to false.

Visible true|false;

If set to false, this display element will initially be hidden. Presumably only useful in conjunction with PopUpDownKey and/or PopUpDownLinked.

If this option is not present, it defaults to true.

Width width;

Specifies the width of the current display element.