====== Define colour pair ======

===== Synopsis =====

    cpair [--foreground <foreground>] [--background <background>] <pair index>

===== Examples =====

=== Redefine the default colour pair as yellow on cyan ===

    cpair --foreground 3 --background 6 0

=== Redefine the default colour pair using 24-bit RGB colours ===

    colour --rgb 0xa0522d 7
    colour --rgb 0x4682b4 4
    cpair --foreground 7 --background 4 0

=== Redefine the editable text colour pair as red on white ===

    cpair --foreground 1 --background 7 4

=== Reset the default colour pair ===

    cpair 0

===== Description =====

Define the specified colour pair index to use the specified foreground colour index and the specified background colour index.  If the foreground colour index is omitted, then a white foreground will be used.  If the background colour index is omitted, then a black or transparent background will be used.

The colour indexes refer to colours as defined using the ''[[:cmd:colour]]'' command.

The default colour pair definitions are:

^ Pair index  ^ Usage            ^ Foreground colour index ^ Background colour index           ^
| 0 | Default colour             | 9 (default: white)      | 9 (default: black or transparent) |
| 1 | Normal user interface text | 7 (white)               | 4 (blue or transparent)           |
| 2 | Highlighted text           | 7 (white)               | 1 (red)                           |
| 3 | Separators                 | 6 (cyan)                | 4 (blue or transparent)           |
| 4 | Editable text              | 0 (black)               | 6 (cyan)                          |
| 5 | Error messages             | 7 (white)               | 1 (red)                           |
| 6 | Help URLs                  | 6 (cyan)                | 4 (blue or transparent)           |
| 7 | PXE menu selection         | 0 (black)               | 7 (white)                         |

===== Command status =====

^ Success   | The colour pair was successfully defined          |
^ Failure   | The colour pair was not successfully defined      |

===== See also =====

  * ''[[:cmd:colour]]''
  * ''[[:cmd:console]]''
  * [[:console|Console configuration]] in iPXE
  * [[:cmd|List of all iPXE commands]]

===== Build options =====

This command is available only when the build option ''[[:buildcfg:CONSOLE_CMD]]'' is enabled.