https://invisible-island.net/cdk/manpage/


cdk_display 3

cdk_display(3)            Library Functions Manual            cdk_display(3)

NAME

       cdk_display - Curses Development Kit Display Capabilities.

SYNOPSIS

       Cdk  has  a  number  of pre-defined display types.  The following are
       outlined in this manual page:

       o How To Use Colors

       o How To Use Different Character Attributes

       o How To Justify Strings

       o How To Use Special Drawing Characters

       o Edit/Display Type Codes (EDisplayType)

DESCRIPTION

       Cdk has special formatting commands which  can  be  included  in  any
       string which add highlights, justification, or even colors to a basic
       string.  These attributes, once set, remain in effect  until  changed
       explicitly, or until the end of the string.

       This manual page outlines and demonstrates how they work.

How To Use Colors

       Cdk  has the capability to display colors in almost every string type
       displayed in a Cdk widget.

       Normally the color pairs are accessed via the COLOR_PAIR macro.   You
       can  still  do  this,  but  creating a string with multiple colors is
       tedious.  That is why the color commands were created.  Use  initCDK-
       Color to create up to 64 color pairs which you can refer to by number
       in strings.

       The color settings are stored directly in the string.  When the  wid-
       get  is  created or activated, the string is converted to take advan-
       tage of any color commands in the string.

       o   To turn on a color pair insert </XX> into the string; where XX is
           a numeric value from 0 to the maximum color pair.

           Color pair 0 is the standard default color pair for the screen.

           If you used initCDKColor, the maximum value for XX is 63 for ter-
           minals supporting 8 ANSI colors.

           If you created color pairs directly using init_pair, the  maximum
           value for XX is implementation-dependent, e.g., 63 (for Unix sys-
           tems) and 255 for ncurses.

           If the terminal  does  not  support  color,  Cdk  uses  the  bold
           attribute.

       o   To turn off a color pair use the format command <!XX> where XX is
           a numeric value from 0 to the maximum color pair.

       The following example demonstrates the use of the color commands.

                     ----------------------------------------
       #include <cdk/cdk.h>

       void main()
       {
          CDKSCREEN   *cdkscreen;
          CDKLABEL    *demo;
          char        *mesg[4];

          cdkscreen = initCDKScreen (NULL);

          /* Start CDK Colors */
          initCDKColor();

          /* Set the labels up.      */
          mesg[0] = "</31>This line should have a yellow foreground and a cyan background.<!31>";
          mesg[1] = "</05>This line should have a white  foreground and a blue background.<!05>";
          mesg[2] = "</26>This line should have a yellow foreground and a red  background.<!26>";
          mesg[3] = "<C>This line should be set to whatever the screen default is.";

          /* Declare the labels.     */
          demo   = newCDKLabel (cdkscreen, CENTER, CENTER, mesg, 4, TRUE, TRUE);

          /* Draw the label          */
          drawCDKLabel (demo, TRUE);
          waitCDKLabel (demo, ' ');

          /* Clean up           */
          destroyCDKLabel (demo);
          destroyCDKScreen (cdkscreen);
          endCDK();
          exit (0);
       }
                     ----------------------------------------

How To Use Different Character Attributes

       Cdk also provides attribute commands which allow different  character
       attributes  to  be  displayed  in  a  Cdk widget.  To use a character
       attribute the format command is </X> where X is one of  several  com-
       mand  characters.  To turn a attribute off use the command <!X>.  The
       following table outlines the command characters:

             +--------------------------------------------------------+
             |Command Character   Character Attribute                 |
             +--------------------------------------------------------+
             |B                   Bold                                |
             |U                   Underline                           |
             |K                   Blink                               |
             |R                   Reverse                             |
             |S                   Standout                            |
             |D                   Dim                                 |
             |N                   Normal                              |
             +--------------------------------------------------------+
       The following example  demonstrates  the  use  of  character  display
       attributes.

                     ----------------------------------------
       #include <cdk/cdk.h>

       void main()
       {
          CDKSCREEN    *cdkscreen;
          CDKLABEL     *demo;
          char         *mesg[4];

          cdkscreen = initCDKScreen (NULL);

          /* Start CDK Colors */
          initCDKColor();

          /* Set the labels up.  */
          mesg[0] = "</B/31>Bold text            yellow foreground / blue background.<!31>";
          mesg[1] = "</U/05>Underlined text      white  foreground / blue background.<!05>";
          mesg[2] = "</K/26>Blinking text        yellow foreground / red  background.<!26>";
          mesg[3] = "<C>This line uses the screen default colors.";

          /* Declare the labels.  */
          demo = newCDKLabel (cdkscreen, CENTER, CENTER, mesg, 4, TRUE, TRUE);

          /* Draw the label */
          drawCDKLabel (demo, TRUE);
          waitCDKLabel (demo, ' ');

          /* Clean up */
          destroyCDKLabel (demo);
          destroyCDKScreen (cdkscreen);
          endCDK();
          exit (0);
       }
                     ----------------------------------------

       Note  that color commands and format commands can be mixed inside the
       same format marker.  The above example underlines the  label  marker,
       which also sets color pair number 2.

How To Justify Strings

       Justification  commands  can left justify, right justify, or center a
       string of text.  To use a justification format in a string  the  com-
       mand <X> is used.  The following table lists the format commands:

            +---------------------------------------------------------+
            |Command           Action.                                |
            +---------------------------------------------------------+
            |<L>               Left Justified. Default if not stated. |
            |<C>               Centered text.                         |
            |<R>               Right justified.                       |
            |<I=X>             Indent the line X characters.          |
            |<B=X>             Bullet. X is the bullet string to use. |
            |<F=X>             Links  in  a file where X is the file- |
            |                  name.  This works only with the viewer |
            |                  widget.                                |
            +---------------------------------------------------------+
       The  following example demonstrates how to use the justification com-
       mands in a Cdk widget.
                     ----------------------------------------
       #include <cdk/cdk.h>

       void main()
       {
          CDKSCREEN    *cdkscreen;
          CDKLABEL     *demo;
          char         *mesg[5];

          cdkscreen = initCDKScreen (NULL);

          /* Start CDK Colors */
          initCDKColor();

          /* Set the labels up.  */
          mesg[0] = "<R></B/31>This line should have a yellow foreground and a blue background.<!31>";
          mesg[1] = "</U/05>This line should have a white  foreground and a blue background.<!05>";
          mesg[2] = "<B=+>This is a bullet.";
          mesg[3] = "<I=10>This is indented 10 characters.";
          mesg[4] = "<C>This line should be set to whatever the screen default is.";

          /* Declare the labels.  */
          demo = newCDKLabel (cdkscreen, CENTER, CENTER, mesg, 5, TRUE, TRUE);

          /* Draw the label */
          drawCDKLabel (demo, TRUE);
          waitCDKLabel (demo, ' ');

          /* Clean up */
          destroyCDKLabel (demo);
          destroyCDKScreen (cdkscreen);
          endCDK();
          exit (0);
       }
                     ----------------------------------------

       The bullet format command can take either a  single  character  or  a
       string.  The bullet in the above example would look like
          + This is a bullet.
       but if we were to use the following command instead
          <B=***>This is a bullet.
       it would look like
          *** This is a bullet.

       A format command must be at the beginning of the string.

How To Use Special Drawing Characters

       Cdk  has  a  set  of special drawing characters which can be inserted
       into any ASCII file.  These characters are encoded using  the  format
       command  "<#XX>"  where  XX is a two-character name.  The char2Chtype
       and chtype2String functions provide conversion to/from curses  chtype
       data (see cdk_util(3)).

       The following table lists the supported special character commands.

             +--------------------------------------------------------+
             |Special_Character   Character                           |
             +--------------------------------------------------------+
             |<#UL>               Upper Left Corner                   |
             |<#UR>               Upper Right Corner                  |
             |<#LL>               Lower Left Corner                   |
             |<#LR>               Lower Right Corner                  |
             +--------------------------------------------------------+
             |<#LT>               Left Tee                            |
             |<#RT>               Right Tee                           |
             |<#TT>               Top Tee                             |
             |<#BT>               Bottom Tee                          |
             +--------------------------------------------------------+
             |<#HL>               Horizontal Line                     |
             |<#VL>               Vertical Line                       |
             +--------------------------------------------------------+
             |<#PL>               Plus Sign                           |
             |<#PM>               Plus or Minus Sign                  |
             |<#DG>               Degree Sign                         |
             |<#CB>               Checker Board                       |
             |<#DI>               Diamond                             |
             |<#BU>               Bullet                              |
             |<#S1>               Scan line 1                         |
             |<#S9>               Scan line 9                         |
             +--------------------------------------------------------+
             |<#LA>               Left Arrow                          |
             |<#RA>               Right Arrow                         |
             |<#TA>               Top Arrow                           |
             |<#BA>               Bottom Arrow                        |
             +--------------------------------------------------------+
       The  character  formats  can  be  repeated  using an optional numeric
       repeat value.  To repeat a character  add  the  repeat  count  within
       parentheses  to the end of the character format.  The following exam-
       ple draws 10 horizontal-line characters:

       <#HL(10)>

       The following example draws a box within a label window:
                     ----------------------------------------
       #include <cdk/cdk.h>

       void main()
       {
          /* Declare variables.  */
          CDKSCREEN    *cdkscreen;
          CDKLABEL     *demo;
          char         *mesg[4];

          cdkscreen = initCDKScreen (NULL);

          /* Start CDK Colors */
          initCDKColor();

          /* Set the labels up.  */
          mesg[0] = "<C><#UL><#HL(26)><#UR>";
          mesg[1] = "<C><#VL></R>This text should be boxed.<!R><#VL>";
          mesg[2] = "<C><#LL><#HL(26)><#LR>";
          mesg[3] = "<C>While this is not.";

          /* Declare the labels.  */
          demo = newCDKLabel (cdkscreen, CENTER, CENTER, mesg, 4, TRUE, TRUE);

          /* Is the label NULL???  */
          if (demo == (CDKLABEL *)NULL)
          {
             /* Clean up the memory.  */
             destroyCDKScreen (cdkscreen);

             /* End curses...  */
             endCDK();

             /* Spit out a message.  */
             printf ("Oops. Can't seem to create the label. Is the window too small?\n");
             exit (1);
          }

          /* Draw the CDK screen.  */
          refreshCDKScreen (cdkscreen);
          waitCDKLabel (demo, ' ');

          /* Clean up */
          destroyCDKLabel (demo);
          destroyCDKScreen (cdkscreen);
          endCDK();
          exit (0);
       }
                     ----------------------------------------

       Notice that drawn text can also be justified.

Edit/Display Type Codes (EDisplayType)

         +----------------------------------------------------------------+
         |Display_Type      Result                                        |
         +----------------------------------------------------------------+
         |vCHAR             Only accepts alphabetic characters.           |
         |vLCHAR            Only accepts alphabetic characters.  Maps the |
         |                  character  to lower case when a character has |
         |                  been accepted.                                |
         |vUCHAR            Only accepts alphabetic characters.  Maps the |
         |                  character  to upper case when a character has |
         |                  been accepted.                                |
         |vHCHAR            Only accepts alphabetic characters.  Displays |
         |                  a  period  (.)  when  a  character  has  been |
         |                  accepted.                                     |
         |vUHCHAR           Only accepts alphabetic characters.  Displays |
         |                  a  period (.) and maps the character to upper |
         |                  case when a character has been accepted.      |
         |vLHCHAR           Only accepts alphabetic characters.  Displays |
         |                  a  period (.) and maps the character to lower |
         |                  case when a character has been accepted.      |
         |vINT              Only accepts numeric characters.              |
         |vHINT             Only accepts numeric characters.  Displays  a |
         |                  period   (.)   when   a  character  has  been |
         |                  accepted.                                     |
         |vMIXED            Accepts any character types.                  |
         |vLMIXED           Accepts any character types.  Maps the  char- |
         |                  acter  to lower case when an alphabetic char- |
         |                  acter has been accepted.                      |
         |vUMIXED           Accepts any character types.  Maps the  char- |
         |                  acter  to upper case when an alphabetic char- |
         |                  acter has been accepted.                      |
         |vHMIXED           Accepts  any  character  types.   Displays  a |
         |                  period   (.)   when   a  character  has  been |
         |                  accepted.                                     |
         |vLHMIXED          Accepts  any  character  types.   Displays  a |
         |                  period  (.)  and  maps the character to lower |
         |                  case when a character has been accepted.      |
         |vUHMIXED          Accepts  any  character  types.   Displays  a |
         |                  period  (.)  and  maps the character to upper |
         |                  case when a character has been accepted.      |
         |vVIEWONLY         Uneditable field.                             |
         +----------------------------------------------------------------+

SEE ALSO

       cdk(3), cdk_binding(3), cdk_screen(3), cdk_util(3)

                                                              cdk_display(3)