How to construct a macro with key=value by \pgfkeys

Question

I just learn \pgfkeys, but don't quite understand how to use it for making a macro with key=value options.

I'd like to give the following simple example as a practice to show my idea.

\documentclass{article}
\usepackage{tikz}

\newcommand{\mycolorbox}[1][]{
  \pgfkeys{
  color/.initial=red,
  text/.initial=some text,
  #1,
  exe/.code=\colorbox{color}{text}
}
}
\begin{document}
\mycolorbox[color=blue, text=This is a practice.]
\end{document}

This does not work. Anyone can help me with this?

Answer 1

You want to define your own namespace for keys and separate key definition from usage.

\documentclass{article}
\usepackage{tikz}

\pgfkeys{/lyl/mycolorbox/.cd, % define your own space
  color/.store in=\mycolorboxcolor,
  text/.store in=\mycolorboxtext,
  color=red!40,
  text=some text,
}

\newcommand{\mycolorbox}[1][]{%
  \begingroup
  \pgfkeys{/lyl/mycolorbox/.cd,#1}%
  \colorbox{\mycolorboxcolor}{\mycolorboxtext}%
  \endgroup
}

\begin{document}

\mycolorbox[color=blue!20]

\mycolorbox[text=This is a practice.]

\mycolorbox[color=blue!20, text=This is a practice.]

\end{document}

The expl3 version:

\documentclass{article}
\usepackage{xcolor}

\ExplSyntaxOn

\keys_define:nn { lyl/mycolorbox }
 {
  color .tl_set:N  = \l__lyl_mycolorbox_color_tl,
  text  .tl_set:N  = \l__lyl_mycolorbox_text_tl,
  color .initial:n = red!40,
  text  .initial:n = some~text,
 }

\NewDocumentCommand{\mycolorbox}{O{}}
 {
  \group_begin:
  \keys_set:nn { lyl/mycolorbox } { #1 }
  \colorbox{\l__lyl_mycolorbox_color_tl}{\l__lyl_mycolorbox_text_tl}
  \group_end:
 }

\ExplSyntaxOff

\begin{document}

\mycolorbox[color=blue!20]

\mycolorbox[text=This is a practice.]

\mycolorbox[color=blue!20, text=This is a practice.]

\end{document}

Answer 2

Another way to store values is inside the key paths themselves (that doesn't mean you don't use as many commands, so this doesn't ease the namespace-heaviness).

\documentclass[]{article}

\usepackage{xcolor}
\usepackage{pgfkeys}

\pgfkeys
  {%
     /mycolorbox/.is family
    ,/mycolorbox
    ,color/.initial=blue
    ,text/.initial=some text
  }
\newcommand\mycolorbox[1][]
  {%
    \begingroup
      \pgfqkeys{/mycolorbox}{#1}%
      \colorbox
        {\pgfkeysvalueof{/mycolorbox/color}}
        {\pgfkeysvalueof{/mycolorbox/text}}%
    \endgroup
  }

\begin{document}
\mycolorbox

\mycolorbox[color=red]

\mycolorbox[text=foobar]
\end{document}

(note: \pgfqkeys{/<path>}{<keys>} is the same as \pgfkeys{/<path>/.cd,<keys>} but faster)

Answer 3

If you're just setting up a simple macro with a few keys (and that's the only interface accessing and using those keys), you could as well build your macro with expkv-cs:

\documentclass[]{article}

\usepackage{xcolor}
\usepackage{expkv-cs}

\ekvcSplit\mycolorbox
  {
     color=blue
    ,text=some text
  }
  {\colorbox{#1}{#2}}%

\begin{document}
\mycolorbox{}

\mycolorbox{color=red}

\mycolorbox{text=foobar}
\end{document}

(expkv-cs defines the macro \mycolorbox with a mandatory argument, if you want to use an optional one, just add a wrapper like: \newcommand\mycolorbox[1][]{\mycolorboxSplit{#1}} and changing the name of the macro after \ekvcSplit to \mycolorboxSplit).