Difference between revisions of "Floating Objects"

From Wiki
Jump to navigation Jump to search
m (add title to first section)
m (Remove TEXpage from code snippets)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
< [[Visuals]] | [[Graphics]] | [[Using Graphics]] | [[Tables_Overview]] >
+
= Introduction =
  
== Introduction ==
+
Floating Objects (floats) are placed (and numbered) automatically, with a configurable (and optional) caption. They are placed at an appropriate position determined by the TeX float placement algorithm. The algorithm has a number of options that can influence float placement.
  
Floating Objects (floats) are placed (and numbered) automatically. They are placed at an appropriate position determined by the TeX float placement algorithm. The algorithm has a number of options that can influence float placement.
+
Most options in the manual (such as {{cmd|placeexternalfigure}}) are described using the generic {{cmd|placefloat}}. Additionally, {{cmd|placelistoffigures}} creates a list of the figures used in the document.
 
 
Most options in the manual (such as {{cmd|placeexternalfigure}}) are described using the generic {{cmd|placefloat}}.
 
  
 
Floats include "graphic", "figure", "table", and "intermezzo". Additional floats can be defined using {{cmd|definefloat}}.
 
Floats include "graphic", "figure", "table", and "intermezzo". Additional floats can be defined using {{cmd|definefloat}}.
Line 40: Line 38:
 
If you don't need to refer to your float, you can leave this parameter out.
 
If you don't need to refer to your float, you can leave this parameter out.
  
== Examples ==
+
= Examples =
 
I will explain the examples in terms of {{cmd|placefigure}} but the same set of options are also valid for other floats.
 
I will explain the examples in terms of {{cmd|placefigure}} but the same set of options are also valid for other floats.
  
Line 70: Line 68:
 
This does not work correctly at a page boundary. The <tt>line</tt> option leaves the space above the figures empty, while the <tt>hang</tt> option also wraps texts above the figure.
 
This does not work correctly at a page boundary. The <tt>line</tt> option leaves the space above the figures empty, while the <tt>hang</tt> option also wraps texts above the figure.
  
==Floats and columns==
+
=Floats and columns=
  
 
This special case is discussed [[Columns#Floats_and_other_limitations_of_columns|here]].
 
This special case is discussed [[Columns#Floats_and_other_limitations_of_columns|here]].
  
==Protruding Floats in Double-Sided Documents==
+
=Floats on empty pages=
 +
 
 +
There’s a way to switch off page headings at full page floats:
 +
 
 +
<texcode>
 +
\startplacefigure[title=Cow,location={page,high,header}]
 +
  \externalfigure[cow.pdf]
 +
\stopplacefigure
 +
</texcode>
 +
 
 +
=Protruding Floats in Double-Sided Documents=
  
 
If you have a double-sided document with wide outer margins then you might want your figures to protrude into the margin. In a double-sided document you need to tell ConTeXt to decide whether to make the figure protrude to the left or the right. This can be done as follows:
 
If you have a double-sided document with wide outer margins then you might want your figures to protrude into the margin. In a double-sided document you need to tell ConTeXt to decide whether to make the figure protrude to the left or the right. This can be done as follows:
Line 100: Line 108:
 
</texcode>
 
</texcode>
  
==Landscape Floats in a Portrait Document==
+
=Landscape Floats in a Portrait Document=
 +
 
 
Wide tables, for example, can be turned and most likely will need to be put on a separate page.
 
Wide tables, for example, can be turned and most likely will need to be put on a separate page.
 
<texcode>
 
<texcode>
Line 111: Line 120:
 
Both the table caption and the contents will be rotated, but not the page header and footer which remain "upright". Notice that one must set the TABLE textwidth to {{cmd|textheight}} in order for the table macros to fit properly.
 
Both the table caption and the contents will be rotated, but not the page header and footer which remain "upright". Notice that one must set the TABLE textwidth to {{cmd|textheight}} in order for the table macros to fit properly.
  
== Floats and section headings ==
+
= Floats and section headings =
By default, section headings don't wrap "around" floating objects. Instead, they will be moved down as far as needed to appear below the float. This behaviour can be controlled using the <tt>aligntitle</tt> option of the {{cmd|setupheads}} or {{cmd|setuphead}} commands.
+
 
 +
By default, section headings don't wrap “around” floating objects. Instead, they will be moved down as far as needed to appear below the float. This behaviour can be controlled using the <tt>aligntitle</tt> option of the {{cmd|setupheads}} or {{cmd|setuphead}} commands.
 +
 
 +
= Captions =
  
== Captions ==
 
 
To change the style of figure(table) captions, use {{cmd|setupcaptions}}.
 
To change the style of figure(table) captions, use {{cmd|setupcaptions}}.
  
 
To use a different (e.g. abbreviated) caption in the list of floats, you can do:
 
To use a different (e.g. abbreviated) caption in the list of floats, you can do:
 +
 +
<texcode>
 +
\startplacefigure[title={A rather long caption},list={A short caption}]
 +
This is the content of the actual figure
 +
\stopplacefigure
 +
</texcode>
 +
 +
In MkII this was possible by:
  
 
<texcode>
 
<texcode>
Line 133: Line 152:
 
</texcode>
 
</texcode>
  
Or in more recent (circa November 2011 and later) versions of ConTeXt:
+
= Float Combinations =
  
<texcode>
+
If you want to place floats besides each other or in a regular matrix,
\startplacefigure[title={A rather long caption},list={A short caption}]
+
each with its own number and caption, you need a float combination:
This is the content of the actual figure
+
 
 +
<context source=yes>
 +
\useMPlibrary [dum]  %% sample images
 +
 
 +
\startplacefigure [location=none]    % disable numbering of outer float
 +
  \startfloatcombination [nx=2, ny=1] % two columns, one row
 +
    \startplacefigure [title=Left]
 +
      \externalfigure [dummy]
 +
    \stopplacefigure
 +
    \startplacefigure [title=Right]
 +
      \externalfigure [dummy]
 +
    \stopplacefigure
 +
  \stopfloatcombination
 +
\stopplacefigure
 +
</context>
 +
 
 +
If you want only one number for the whole thing, you may use a regular combination within a float:
 +
 
 +
<context source=yes>
 +
\useMPlibrary [dum]  %% sample images
 +
 
 +
\startplacefigure [title=My combination]
 +
  \startcombination [nx=2, ny=1]
 +
    \startcontent \externalfigure [dummy] \stopcontent
 +
    \startcaption Left                    \stopcaption
 +
    \startcontent \externalfigure [dummy] \stopcontent
 +
    \startcaption Right                  \stopcaption
 +
  \stopcombination
 +
\stopplacefigure
 +
</context>
 +
 
 +
 
 +
See also {{cmd|startcombination}}, {{cmd|startfloatcombination}} and [[Combinations]].
 +
 
 +
= Subfloats =
 +
Subfloatnumbering creates subfigures sharing a mutual figure prefix and an
 +
individual subfigure designator (e.g. figure 1a), figure 1b, etc.). The command {{cmd|startsubfloatnumbering}} is used for this.
 +
 
 +
<context source=yes>
 +
\useMPlibrary [dum]  %% sample images
 +
 
 +
\startsubfloatnumbering
 +
  \startplacefigure [title=Alpha]
 +
    \externalfigure
 +
  \stopplacefigure
 +
 
 +
  \startplacefigure [title=Beta]
 +
    \externalfigure
 +
  \stopplacefigure
 +
\stopsubfloatnumbering
 +
</context>
 +
 
 +
Subfloats can also be used with floatcombinations:
 +
 
 +
<context source=yes>
 +
\useMPlibrary [dum]  %% sample images
 +
 
 +
\startplacefigure [location=none]
 +
  \startsubfloatnumbering
 +
    \startfloatcombination [nx=2, ny=1]
 +
      \startplacefigure [title=Left,  reference=fig:left]  \externalfigure \stopplacefigure
 +
      \startplacefigure [title=Right, reference=fig:right] \externalfigure \stopplacefigure
 +
    \stopfloatcombination
 +
  \stopsubfloatnumbering
 
\stopplacefigure
 
\stopplacefigure
</texcode>
 
  
== Flushing floats ==
+
See \in{figure}[fig:left] and \in{figure}[fig:right].
 +
</context>
 +
 
 +
 
 +
See also {{cmd|startcombination}}, {{cmd|startfloatcombination}}, [[Combinations]] and {{cmd|startsubfloatcombination}}.
 +
 
 +
= Flushing floats =
  
 
The command {{cmd|placefloats}} outputs all pending floats.
 
The command {{cmd|placefloats}} outputs all pending floats.
 +
 +
[[Category:Basics]]
 +
[[Category:Layout]]

Latest revision as of 15:13, 28 November 2021

Introduction

Floating Objects (floats) are placed (and numbered) automatically, with a configurable (and optional) caption. They are placed at an appropriate position determined by the TeX float placement algorithm. The algorithm has a number of options that can influence float placement.

Most options in the manual (such as \placeexternalfigure) are described using the generic \placefloat. Additionally, \placelistoffigures creates a list of the figures used in the document.

Floats include "graphic", "figure", "table", and "intermezzo". Additional floats can be defined using \definefloat.

\placefloat[place][reference]{caption}{some float}

place is one or several (comma separated) of:

preferenceresult
leftleft of text
rightright of text
herepreferably here
topat top of page
bottomat bottom of page
inleftin left margin
inrightin right margin
inmarginin the margin (left or right)
marginin the margin (margin float)
pageon a new (empty) page
oppositeon the left page
90orientation (rotation angle), both caption and contents
alwaysprecedence over stored floats
forceper se here
split(For TABLES only) split tables

(table copied from the manual)

\placefigure and \placetable also accept the same set of options, and allow to create floating figures and captions respectively.

reference

If you don't need to refer to your float, you can leave this parameter out.

Examples

I will explain the examples in terms of \placefigure but the same set of options are also valid for other floats.

  • If you do not want a caption
\placefigure[none] {} {\externalfigure[figurename]}


  • If you do not want the figure to be numbered (but still want the caption)
\placefigure [nonumber] {caption} {\externalfigure[figurename]}
  • Suppose you want the figure to be placed on the right side of the page, a few lines into the paragraph, and want the rest of the paragraph to wrap around the figure
\placefigure [right,2*line] {caption} {\externalfigure[figurename]}

or

\placefigure [right,2*hang] {caption} {\externalfigure[figurename]}

This does not work correctly at a page boundary. The line option leaves the space above the figures empty, while the hang option also wraps texts above the figure.

Floats and columns

This special case is discussed here.

Floats on empty pages

There’s a way to switch off page headings at full page floats:

\startplacefigure[title=Cow,location={page,high,header}]
   \externalfigure[cow.pdf]
\stopplacefigure

Protruding Floats in Double-Sided Documents

If you have a double-sided document with wide outer margins then you might want your figures to protrude into the margin. In a double-sided document you need to tell ConTeXt to decide whether to make the figure protrude to the left or the right. This can be done as follows:

\definefloat[textmarginfigure][textmarginfigures]
\setupfloat[textmarginfigure][location=inner]
\placetextmarginfigure{\externalfigure[figurename]}

The following code gives a full example that can be pasted into live ConTeXt:

\setuppagenumbering [alternative=doublesided]
\setuplayout[location=middle,backspace=2pc, width=20pc]
\definefloat[textmarginfigure][textmarginfigures]
\setupfloat[textmarginfigure][location=inner]
\starttext
\input knuth
\placetextmarginfigure[here]{}{\externalfigure[figurename][width=30pc]}
\input knuth
\placetextmarginfigure[here]{}{\externalfigure[figurename][width=30pc]}
\input knuth
\stoptext

Landscape Floats in a Portrait Document

Wide tables, for example, can be turned and most likely will need to be put on a separate page.

\startplacetable [location={page,90},title=Table caption]
    \bTABLE [textwidth=\textheight]
        put a wide table here...
    \eTABLE
\stopplacetable

Both the table caption and the contents will be rotated, but not the page header and footer which remain "upright". Notice that one must set the TABLE textwidth to \textheight in order for the table macros to fit properly.

Floats and section headings

By default, section headings don't wrap “around” floating objects. Instead, they will be moved down as far as needed to appear below the float. This behaviour can be controlled using the aligntitle option of the \setupheads or \setuphead commands.

Captions

To change the style of figure(table) captions, use \setupcaptions.

To use a different (e.g. abbreviated) caption in the list of floats, you can do:

\startplacefigure[title={A rather long caption},list={A short caption}]
This is the content of the actual figure
\stopplacefigure

In MkII this was possible by:

\defineselector[caption][max=2,n=2]
\starttext
\setupselector[caption][n=1]
\completelistoffigures
\setupselector[caption][n=2]
\placefigure[][]
{\select{caption}
 {Short caption for list}
 {A rather longer caption which will appear below the figure itself}}
 {This is the content of the actual figure}
\stoptext

Float Combinations

If you want to place floats besides each other or in a regular matrix, each with its own number and caption, you need a float combination:

\useMPlibrary [dum]  %% sample images

\startplacefigure [location=none]     % disable numbering of outer float
  \startfloatcombination [nx=2, ny=1] % two columns, one row
    \startplacefigure [title=Left]
      \externalfigure [dummy]
    \stopplacefigure
    \startplacefigure [title=Right]
      \externalfigure [dummy]
    \stopplacefigure
  \stopfloatcombination
\stopplacefigure

If you want only one number for the whole thing, you may use a regular combination within a float:

\useMPlibrary [dum]  %% sample images

\startplacefigure [title=My combination]
  \startcombination [nx=2, ny=1]
    \startcontent \externalfigure [dummy] \stopcontent
    \startcaption Left                    \stopcaption
    \startcontent \externalfigure [dummy] \stopcontent
    \startcaption Right                   \stopcaption
  \stopcombination
\stopplacefigure


See also \startcombination, \startfloatcombination and Combinations.

Subfloats

Subfloatnumbering creates subfigures sharing a mutual figure prefix and an individual subfigure designator (e.g. figure 1a), figure 1b, etc.). The command \startsubfloatnumbering is used for this.

\useMPlibrary [dum]  %% sample images

\startsubfloatnumbering
  \startplacefigure [title=Alpha]
    \externalfigure
  \stopplacefigure

  \startplacefigure [title=Beta]
    \externalfigure
  \stopplacefigure
\stopsubfloatnumbering

Subfloats can also be used with floatcombinations:

\useMPlibrary [dum]  %% sample images

\startplacefigure [location=none]
  \startsubfloatnumbering
    \startfloatcombination [nx=2, ny=1]
      \startplacefigure [title=Left,  reference=fig:left]  \externalfigure \stopplacefigure
      \startplacefigure [title=Right, reference=fig:right] \externalfigure \stopplacefigure
    \stopfloatcombination
  \stopsubfloatnumbering
\stopplacefigure

See \in{figure}[fig:left] and \in{figure}[fig:right].


See also \startcombination, \startfloatcombination, Combinations and \startsubfloatcombination.

Flushing floats

The command \placefloats outputs all pending floats.