New color command \colorPlus[<color-when-printed>]{<color-in-PDF>} that behaves differently when viewed and printed

Question

The aim is to define a new command \colorPlus[<color-when-printed>]{<color-in-PDF>} that

• works exactly like the usual \color{<color-in-PDF-and-print>} when used without optional argument as in \colorPlus{<color-in-PDF};
• does some osgx2-type magic when an optional argument is given. For example, \colorPlus[black]{red} will make text show up red in the PDF but be black when printed.

According to some old comments from 2015 (1, 2) by Mariano Suárez-Álvarez and Herbert/user2478, this should be possible. The question is then how to do it.

You may change the syntax of \colorPlus, or use some existing commands instead, if you believe to have a better syntax.

As a test, change \color{red} in the following MWE to \colorPlus{black}{red} to see if your solution is working.

\documentclass{book}
\usepackage{tocloft}
\usepackage{titlesec}
\usepackage{xcolor}
\usepackage[colorlinks=true, linkcolor=blue, hypertexnames=false, linktoc=all]{hyperref} % blue internal links for document; in TOC, entry name and page nr are links
\usepackage[ocgcolorlinks]{ocgx2}

%%% Definition of \colorPlus{}  

%%%

\renewcommand{\cftsecpagefont}{\color{red}} % change "\color{red}" to \colorPlus[black]{red} as a test

\begin{document}
    {\hypersetup{hidelinks}
    \tableofcontents} 
    
    \chapter{Example chapter}
    
    \section{Example section}
    
    \subsection{Example subsection}
    
This is some text.
\end{document}

The MWE is essentially from my earlier question How to make red page numbers in table of contents while 'linktoc=all' and '\hypersetup{linkcolor=black}' are present? and samcarter_is_at_topanswers.xyz's answer. The section page number is red when viewed in PDF (but, in this case, also when printed).

Answer 1

colorPlus needs to be implemented as an environment, since filling the font outlines with optional colours depending on OC settings is done after the text has been inserted.

So, here is a solution based on internal code from ocgx2. Also, tocloft commands \cftsecfillnum, \cftsecpagefont and \cftsecafterpnum need to be redefined. Note that pdfmanagement-testphase must be enabled for the code to work.

The new environment is

\begin{colorPlus}[<printing colour>]{<viewing colour>}
...
\end{colorPlus}

Named colours and xcolor colour expressions can be used for <printing color> and <viewing colour>.

Works in Acrobat Reader and Chrome/Chromium PDF viewer plugin.

\DocumentMetadata{} % pdfmanagement-testphase needs to be enabled
\documentclass{book}
\usepackage{tocloft}
\usepackage{titlesec}
\usepackage{xcolor}
\usepackage[colorlinks=true, linkcolor=blue, hypertexnames=false, linktoc=all]{hyperref} % blue internal links for document; in TOC, entry name and page nr are links
\usepackage[ocgcolorlinks]{ocgx2}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{colorPlus}[<printing color>]{<viewing colour>}
% ...
% \end{colorPlus}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\ExplSyntaxOn
\NewDocumentEnvironment{colorPlus}{om}{
  \color_group_begin:
  \IfValueTF{#1}{ % optional printing colour given
    \ocgxii_colorlinks_init: % create OCGs for printing and viewing
    \color_select:n{#1}
    \color_export:nnN{#2}{backend}\l_tempb_tl
    \tl_set:Nx\l_tempa_tl{\tl_item:Nn\l_tempb_tl{1}} % model
    \tl_set:Nx\l_tempb_tl{\tl_item:Nn\l_tempb_tl{2}} % components
    \str_replace_all:Nnn\l_tempb_tl{~}{,}
    \tl_set:Nx\g_ocgxii_lnkcol_tl{{\l_tempa_tl}{\l_tempb_tl}}
    \ocgxii_colourlink_begin:
  }{
    \color_select:n{#2}
  }
  \ignorespaces
}{
  \unskip
  \IfValueT{#1}{\ocgxii_colourlink_end:}
  \color_group_end:
}
\ExplSyntaxOff
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\makeatletter
\renewcommand{\cftsecfillnum}[1]{%
  {\cftsecleader}\nobreak
  \cftsecpagefont\makebox[\@pnumwidth][\cftpnumalign]{#1}\cftsecafterpnum\par
}
\makeatother
\renewcommand{\cftsecpagefont}{\begin{colorPlus}[black]{blue}}
\renewcommand{\cftsecafterpnum}{\end{colorPlus}}

\begin{document}
{\hypersetup{hidelinks}
\tableofcontents} 

\chapter{Example chapter}

\section{Example section}

\subsection{Example subsection}
    
This is text in default colour.
\begin{colorPlus}[black!50!green]{blue}
The displayed and printed colours of this text may be different.
\end{colorPlus}
Again, text in default colour.
\end{document}

Answer 2

Not a full answer but too long for a comment.

ocgcolorlinks works by surrounding text in the PDF with OC markers:

/OC/OCPrint BDC
% stuff that should be used when printed
/EMC
/OC/OCView BDC
% stuff that should be used when view
EMC

Sadly it looks as if the "stuff" can't be simply a color instruction. There must be something that is drawn (text or graphic). That makes it difficult to handle content that contains line breaks or page breaks.

hyperref avoids problems with breaks by putting the link into a box and then typesetting it twice with different OC-settings, so it can handle only short pieces of text. The ocgx2 package allows line breaks by using clipping: it puts in the OC-settings large colored rectangles which cover the whole page and then changes the rendering mode of the text to clipping, so basically the text is cut out of the background. To handle page breaks the package stores a lot of info and reinstates the status at the begin of the next shipout. While the ocgx2-trick is quite ingenious I wouldn't be confident that it works well if the document is meant for professional printing (but I never tried) and I don't know how it behaves for long pieces of texts.

Now in your example you only want to color a short piece of text, and so the ocgx2 method is not needed. The main problems here are at first that as you use the ocgcolorlinks and the linktoc=all you already have OC-markers and so you get nesting. And as second that to print the text twice with the hyperref method you need to capture the text in a box. So you can't do simply a \colorPlus{red} and hope that it affects following text.