8

According to the tcolorbox package's user manual, the \newtcolorbox macro's usage is as follows (p. 15).

newtcolorbox

The following is given as a usage example. (p. 15).

newtcolorbox usage example

Here's what I don't understand about this example.

  1. In the definition part: What do the empty square brackets mean? That there are no defaults, i.e. that the 2 options are mandatory? If so, why not simply omit these brackets, as in the following example that is given on the same page?

A mandatory option

  1. In the usage part: Why is the first argument ([colback=yellow]) written within square brackets, whereas the second argument ({Hello there}) written within curly braces? If there were more than 2 arguments, how would they be specified?
2
  • 2
    this is the same syntax for optional argument definitions as \newcommand which also can only declare commands with a single optional argument, (optional arguments in latex are always in [] to answer your 2nd question) May 24 '17 at 16:55
  • 1
    There is a default, and it's empty. The empty set is different from “no set”, isn't it?
    – egreg
    May 24 '17 at 17:20
8

The definition is analogous to what is offered by \newcommand where you can define something via

\newcommand{\mycmd}[2][x]{optional: #1, mandatory: #2}

which defines a command \mycmd to take two arguments [2]. The first argument is optional and will take the value x if you don't use it. So, \mycmd{a} is valid, as is \mycmd[b]{a}.

Specific to your questions:

  1. In the definition part: What do the empty square brackets mean? That there are no defaults, i.e. that the 2 options are mandatory? If so, why not simply omit these brackets, as in the following example that is given on the same page?

The empty square brackets refer to the fact that the newly-defined tcolorbox command will take a single optional argument, and the default value for that optional argument if it isn't specified by the user will be blank.

  1. In the usage part: Why is the first argument ([colback=yellow]) written within square brackets, whereas the second argument ({Hello there}) written within curly braces? If there were more than 2 arguments, how would they be specified?

This is because the creation of mybox was defined with

\newtcolorbox{mybox}[2][]

in the first and

\newtcolorbox{mybox}[1]

in the second.

The first states that mybox will take two arguments [2] of which the first will be optional and default to "blank" if not supplied. The second states that mybox will only take a single argument [1] and that it is a mandatory argument.

If you want, say, 5 arguments, all mandatory, then you'd use

\newtcolorbox{mybox}[5]

If you want a single, optional argument, together with (say) 3 mandatory arguments, then use

\newtcolorbox{mybox}[4][default]

where default is the default definition of the optional argument if it's not specified. Moreover, the optional argument is always the first #1 parameter.

2
  • Thanks. There can never be more than a single optional argument?
    – Evan Aad
    May 24 '17 at 17:22
  • 1
    @EvanAad: With the default usage in \newtcolorbox, no. It matches what you can do with \newcommand which provides only a single, optional argument. However, that's usually what is sufficient, as you can define key-value combinations in the optional argument that covers multiple scenarios. There is also \DeclareTColorBox for specifying a varied interface as can be seen in Christian's answer.
    – Werner
    May 24 '17 at 17:25
9

The [] is empty here in the first example, but allows for specification of optional arguments to the call of the mybox environment, i.e. \begin{mybox}[colback=yellow]{Foo} title would have a yellow background and the the title foo. The second example would not allow for optional arguments, that's all.

The definition of box environments with two or more mandatory arguments is as usual with \newcommand: \newtcolorbox{foo}[2]{options}.

If more optional arguments are necessary, use the \DeclareTColorBox feature of tcolorbox.

\documentclass{article}

\usepackage[most]{tcolorbox}

\newtcolorbox{mybox}[2][]{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=-2mm},
title=#2,#1}


\newtcolorbox{myboxwithtwoparameters}[2]{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=-2mm},
title=#2,code={\addtocontents{toc}{#2}}}


\DeclareTColorBox{mytotalbox}{O{}mO{-2mm}}{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=#3},
title=#2,#1}


\begin{document}
\tableofcontents
\begin{mybox}[colback=yellow]{Hello there}
This is my own box with a mandatory title
and options.
\end{mybox}

\begin{myboxwithtwoparameters}{Hello there}{Hello Darkness my old friend}
Foo
\end{myboxwithtwoparameters}

\begin{mytotalbox}[colback=yellow]{Hello there}[-5mm]
This is my own box with a mandatory title
and options.
\end{mytotalbox}


\end{document}

enter image description here

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.