Layout Files
Prev | Chapter 5. Customizing Bless | Next

## Layout Files

The way Bless presents the data is highly customizable. The configuration is done through layout description files. Currently there is no way to graphically edit the layouts but one is planned for a later version.

### Selecting a layout

Bless searches for layout description files in the `$XDG_CONFIG_HOME/bless/layouts` directory (usually $HOME/.config/bless/layouts). You can preview and select the available layouts with the layout selection dialog, which can be accessed by using View → Layouts.

### Creating Layout Files

Layout description files are XML files ending with the .layout suffix. They consist of the <layout> tag which contains a series of <area> tags that describe each area in the layout. The <area> tag takes one attribute, type, which defines the type of the area. The valid values for type are:

Type | Description
--- | ---
hexadecimal | Displays the data in hexadecimal format.
decimal | Displays the data in decimal format.
octal | Displays the data in octal format.
binary | Displays the data in binary format.
ascii | Displays the data in ascii format.
offset | Displays the data offset.
separator | A vertical line that visually separates areas.

For example, the following simple layout file:

    <layout>
    	<area type="offset"></area>
    	<area type="hexadecimal"></area>
    	<area type="offset"></area>
    	<area type="separator"></area>
    	<area type="ascii"></area>
    </layout>

produces the standard offset-hex-ascii view with default colors:

Figure 5.4. Standard offset-hex-ascii view

Each area may include additional options about how to display the data. Some options are available to all areas whereas others are area-specific. The options that aren't explicitly defined assume their default values. Also if an option is specified for an area that doesn't support it, the option is just ignored.

Option | Values | Description | Areas
--- | --- | --- | ---
display | see below | The fonts and colors that should be used for the display. | all
case | upper|lower | Whether to display hexadecimal values using lowercase or uppercase. | offset, hexadecimal
grouping | #int | The number of bytes that should be grouped together in each column. | hexadecimal, decimal, octal, binary
bpr | #int | The number of bytes on each row in the area (see below for more information) | hexadecimal, decimal, octal, binary, ascii
bytes | #int | The number of bytes which will be used to display offsets (default 4) | offset

#### The bpr option

The <bpr> (bytes per row) option sets the (maximum) number of bytes that each row in an area can have. If it is not specified, the number of bytes on each row changes dynamically in order to fill the whole available width. If it is specified in at least one area in the layout all the areas in the layout conform to the specified restriction. In case of a conflict, for example when two areas specify different bprs, the smallest value is used. Finally, if there is a conflict between bpr and grouping values, the highest value that conforms to the grouping and is below the bpr is used (eg if bpr=5 and grouping=2 the bytes per row will be 4).

#### The display option

The <display> option is the most complicated of the lot and deserves additional explanation.

Bless distinguishes between even and odd rows, and even and odd columns. You can choose how to color each of the above items thus creating a visual result tailored to your needs. This is achieved by using the <display> tag. Note that the first row and column are numbered as 0 and are therefore considered even.

A <display> tag may contain a <font> tag which sets the font family and size to use for displaying data in the area (eg "Courier 10"). The font should be a monospaced font, otherwise the data in the area won't be displayed correctly. It is also advised to use same sized fonts in all the areas so that the data is correctly aligned.

A <display> tag may also contain a <evenrow> and a <oddrow> tag which describe how the even and odd rows will look like. Each of the <evenrow> and <oddrow> tags may contain a <evencolumn>, an <oddcolumn>, a <selectedcolumn> and a <patternmatchcolumn> tag. The first two describe the appearance of the respective columns under normal conditions (no highlighting). The <selectedcolumn> tag describes the appearance of selected bytes and the <patternmatchcolumn> tag the appearance of the highlighted bytes that match the selected bytes (see the section called “Selecting a range of data”). The description for all the above is accomplished by using the <foreground> and <background> tags which specify the foreground and background colors to use.

The colors can be specified either by name (eg dark blue) or by an RGB triad (eg #ff004e).

Figure 5.5. Display tag hierarchy

An example:

    <layout>
        <area type="offset">
            <display>
                <evenrow>
                    <evencolumn>
                        <foreground>dark red</foreground>
                    </evencolumn>
                </evenrow>
                <oddrow>
                    <evencolumn>
                        <foreground>dark red</foreground>
                    </evencolumn>
                </oddrow>
            </display>
        </area>

        <area type="separator">
            <display>
                <evenrow>
                    <evencolumn>
                        <foreground>dark green</foreground>
                        <background>white</background>
                    </evencolumn>
                </evenrow>
            </display>
        </area>

        <area type="hexadecimal">
            <grouping>2</grouping>
            <case>upper</case>
            <display>
                <evenrow>
                    <selectedcolumn>
                        <foreground>white</foreground>
                        <background>#8faec8</background>
                    </selectedcolumn>
                </evenrow>
                <oddrow>
                    <evencolumn>
                        <background>#eeeeee</background>
                    </evencolumn>
                    <oddcolumn>
                        <background>#eeeeee</background>
                    </oddcolumn>
                    <selectedcolumn>
                        <foreground>white</foreground>
                        <background>#7b96ac</background>
                    </selectedcolumn>
                </oddrow>
            </display>
        </area>

        <area type="separator">
            <display>
                <evenrow>
                    <evencolumn>
                        <foreground>dark green</foreground>
                        <background>white</background>
                    </evencolumn>
                </evenrow>
            </display>
        </area>

        <area type="decimal">
        </area>

        <area type="separator">
            <display>
                <evenrow>
                    <evencolumn>
                        <foreground>dark green</foreground>
                        <background>white</background>
                    </evencolumn>
                </evenrow>
            </display>
        </area>

        <area type="binary">
        </area>
    </layout>

The result is:

Figure 5.6. Example layout

### Note

Not all font options are used in all areas. The hexadecimal, decimal, octal and binary areas use all options. The ascii, offset and separator areas do not use the <oddcolumn> tag.

### Note

The */evencolumn/background colors are considered the primary background colors for their respective row. They are used to paint all parts of the row that are not otherwise painted (eg space between columns). The evenrow/evencolumn/background color is also considered the main background color of the area and is used to paint the unused parts of the area.

Prev | Up | Next
Preferences | Home | Extending with plugins