datacursormode

データカーソルモードの有効化

説明

データヒントは、個々のデータ点に関する情報を表示する小さなテキストボックスです。R2018b より前のリリースでは、関数 datacursormode を使用してデータヒントを作成および編集します。datacursormode を使用してデータカーソルマネージャーオブジェクトを作成することで、データヒントの外観と動作を制御します。

R2018b 以降では、代わりに組み込み操作を使用してデータヒントを作成および編集できます。組み込み操作ではモードを有効にする必要がなく、操作モードよりも応答が高速です。組み込み操作の詳細については、チャートの対話機能の制御を参照してください。

線グラフ、棒グラフ、ヒストグラム、表面グラフを含むほとんどのチャートで、データヒントはサポートされています。データヒントをサポートするチャートには通常、座標軸ツールバーにデータヒントアイコンが表示されます。

作成

構文

datacursormode on

datacursormode off

datacursormode

datacursormode(fig,___)

dcm = datacursormode

dcm = datacursormode(fig)

説明

datacursormode on は、現在の Figure 内のチャートでデータカーソルモードをオンにします。データカーソルモードがオンの状態でデータ点をクリックすると、データヒントが作成されます。複数のデータヒントを作成するには、Shift キーを押したままデータ点をクリックします。

datacursormode off はデータカーソルモードをオフにします。このコマンドを実行しても既存のデータヒントは削除されません。一部の組み込み操作は、モードに関係なく既定で有効になっています。組み込みのデータヒント操作を無効にするには、関数 disableDefaultInteractivity を使用します。

datacursormode は、データカーソルモードの 'on' と 'off' を切り替えます。この構文は、datacursormode toggle と同じです。

datacursormode(fig,___) は、指定された Figure 内のチャートでデータカーソルモードを設定します。追加引数を 'on'、'off' または 'toggle' として指定します。たとえば、datacursormode(fig,'on') を使用します。

例

dcm = datacursormode は、現在の Figure に対してデータカーソルマネージャーオブジェクトを作成します。この構文は、データカーソルモード、データヒントの表示スタイル、データヒントのテキスト形式を制御する際に便利です。

dcm = datacursormode(fig) は、指定された Figure に対してデータカーソルマネージャーオブジェクトを作成します。

入力引数

すべて展開する

`fig` — ターゲット Figure
`Figure` オブジェクト

ターゲット Figure。Figure オブジェクトとして指定します。

プロパティ

すべて展開する

`SnapToDataVertex` — 最も近いデータ点での表示
`'on'` (既定値) | `'off'`

最も近いデータ点での表示。次のいずれかの値として指定します。

'on' – 最も近いデータ点にデータヒントを表示します。最も近いデータ点は、チャートのタイプによって異なります。たとえば、線グラフでは、最も近い点は指定された位置からのユークリッド距離が最も小さいものです。
'off' – データ点の間であっても、クリックした位置にデータヒントを表示します。

`DisplayStyle` — データヒントの表示スタイル
`'datatip'` (既定値) | `'window'`

データヒントの表示スタイル。次の値のいずれかとして指定します。

'datatip' – データヒントをデータ値に付加される小さいテキストボックスとして表示します。複数のデータヒントを作成するには、Shift キーを押したままデータ点を選択します。データカーソルモードをオフにしても、既存のデータヒントはチャートに残ります。
'window' – データヒントを Figure 内の移動可能なウィンドウに表示します。表示スタイルが 'window' の場合、一度に表示できるデータヒントは 1 つだけです。データカーソルモードをオフにすると、ウィンドウが閉じます。

`Interpreter` — テキストインタープリター
`'tex'` (既定値) | `'latex'` | `'none'`

テキストインタープリター。次の値のいずれかとして指定します。

'tex' — TeX マークアップのサブセットを使用して文字を解釈します。
'latex' — LaTeX マークアップを使用して文字を解釈します。
'none' — リテラル文字を表示します。

TeX マークアップ

MATLAB^® では、既定で TeX マークアップのサブセットをサポートしています。TeX マークアップを使用して、上付き文字や下付き文字の追加、フォントのタイプや色の変更、テキストへの特殊文字の挿入を行うことができます。

修飾子の効果はテキストの末尾まで適用されます。上付き文字と下付き文字は例外であり、次の 1 文字または中かっこで囲まれた文字にのみ適用されます。インタープリターを 'tex' に設定した場合にサポートされる修飾子は次のとおりです。

修飾子	説明	例
`^{ }`	上付き文字	`'text^{superscript}'`
`_{ }`	下付き文字	`'text_{subscript}'`
`\bf`	太字フォント	`'\bf text'`
`\it`	イタリックフォント	`'\it text'`
`\sl`	斜体フォント (通常はイタリックフォントと同じ)	`'\sl text'`
`\rm`	標準フォント	`'\rm text'`
`\fontname{specifier}`	フォント名 — `specifier` をフォントファミリの名前に置き換えます。これは他の修飾子と組み合わせて使用できます。	`'\fontname{Courier} text'`
`\fontsize{specifier}`	フォントサイズ — `specifier` をポイント単位の数値スカラーに置き換えます。	`'\fontsize{15} text'`
`\color{specifier}`	フォントの色 — `specifier` を、`red`、`green`、`yellow`、`magenta`、`blue`、`black`、`white`、`gray`、`darkGreen`、`orange`、`lightBlue` の色のいずれかに置き換えます。	`'\color{magenta} text'`
`\color[rgb]{specifier}`	フォントのカスタムの色 — `specifier` を RGB 3 成分に置き換えます。	`'\color[rgb]{0,0.5,0.5} text'`

次の表に、'tex' インタープリターでサポートされる特殊文字を示します。

文字列	記号	文字列	記号	文字列	記号
`\alpha`	α	`\upsilon`	υ	`\sim`	~
`\angle`	∠	`\phi`		`\leq`	≤
`\ast`	`*`	`\chi`	χ	`\infty`	∞
`\beta`	β	`\psi`	ψ	`\clubsuit`	♣
`\gamma`	γ	`\omega`	ω	`\diamondsuit`	♦
`\delta`	δ	`\Gamma`	Γ	`\heartsuit`	♥
`\epsilon`	ϵ	`\Delta`	Δ	`\spadesuit`	♠
`\zeta`	ζ	`\Theta`	Θ	`\leftrightarrow`	↔
`\eta`	η	`\Lambda`	Λ	`\leftarrow`	←
`\theta`	θ	`\Xi`	Ξ	`\Leftarrow`	⇐
`\vartheta`	ϑ	`\Pi`	Π	`\uparrow`	↑
`\iota`	ι	`\Sigma`	Σ	`\rightarrow`	→
`\kappa`	κ	`\Upsilon`	ϒ	`\Rightarrow`	⇒
`\lambda`	λ	`\Phi`	Φ	`\downarrow`	↓
`\mu`	µ	`\Psi`	Ψ	`\circ`	º
`\nu`	ν	`\Omega`	Ω	`\pm`	±
`\xi`	ξ	`\forall`	∀	`\geq`	≥
`\pi`	π	`\exists`	∃	`\propto`	∝
`\rho`	ρ	`\ni`	∍	`\partial`	∂
`\sigma`	σ	`\cong`	≅	`\bullet`	•
`\varsigma`	ς	`\approx`	≈	`\div`	÷
`\tau`	τ	`\Re`	ℜ	`\neq`	≠
`\equiv`	≡	`\oplus`	⊕	`\aleph`	ℵ
`\Im`	ℑ	`\cup`	∪	`\wp`	℘
`\otimes`	⊗	`\subseteq`	⊆	`\oslash`	∅
`\cap`	∩	`\in`	∈	`\supseteq`	⊇
`\supset`	⊃	`\lceil`	⌈	`\subset`	⊂
`\int`	∫	`\cdot`	·	`\o`	ο
`\rfloor`	⌋	`\neg`	¬	`\nabla`	∇
`\lfloor`	⌊	`\times`	x	`\ldots`	...
`\perp`	⊥	`\surd`	√	`\prime`	´
`\wedge`	∧	`\varpi`	ϖ	`\0`	∅
`\rceil`	⌉	`\rangle`	〉	`\mid`	\|
`\vee`	∨	`\langle`	〈	`\copyright`	©

LaTeX マークアップ

LaTeX マークアップを使用するには、インタープリターを 'latex' に設定します。テキストをドル記号で囲みます。たとえば、インラインモードでは '$\int_1^{20} x^2 dx$'、表示モードでは '$$\int_1^{20} x^2 dx$$' を使用します。

テキストは LaTeX の既定のフォントスタイルで表示され、フォントスタイルを変更するには、LaTeX マークアップを使用します。

LaTeX インタープリターで使用できるテキストの最大サイズは 1200 文字です。複数行のテキストの場合は、さらに 1 行につき 10 文字ほど文字数が少なくなります。

LaTeX システムの詳細については、LaTeX プロジェクトの Web サイト (https://www.latex-project.org/) を参照してください。

`Enable` — データカーソルモード
`'off'` (既定値) | `'on'`

データカーソルモード。'off' または 'on' として指定します。

`UpdateFcn` — データヒントのテキストを書式設定するコールバック関数
`[]` (既定値) | 関数ハンドル

データヒントのテキストを書式設定するコールバック関数。関数ハンドルとして指定します。

このプロパティを使用して、データヒントの内容を書式設定します。MATLAB は次の 2 つの引数をコールバック関数に渡します。

empty – 空の引数。これが使用されないことを示すには、関数の中でこれをチルダ文字 (~) に置き換えます。
info – データヒントに関する情報を含む構造体。info 引数には Target と Position の 2 つのフィールドがあります。Target フィールドには DataTipTemplate プロパティをもつオブジェクトが含まれます。Position フィールドにはデータヒントの座標が含まれます。

関数は MATLAB パス上または現在のフォルダー内になければなりません。あるいは、データヒントのコンテキストメニューから [関数の更新]、[ファイルから選択] を選択すると、MATLAB パス上に存在しない関数を選択できます。

コールバックの詳細については、コールバック定義を参照してください。

`Figure` — figure オブジェクト
`Figure` オブジェクト

このプロパティは読み取り専用です。

データヒントが表示される Figure オブジェクト。

オブジェクト関数

getCursorInfo

info = getCursorInfo(dcm) は、Figure 内の各データヒントのターゲットと座標を返します。info は以下のフィールドを含む構造体のベクトルです。

Target – DataTipTemplate プロパティをもつオブジェクト (Line、Histogram、Surface、FunctionLine など)。
Position – データヒントの座標。座標の解釈は、座標軸のタイプによって異なります。たとえば、直交座標軸の座標は、データと同じ単位の x、y および z です。
DataIndex (Line オブジェクトのみ) – プロットデータのインデックス。たとえば、直交座標軸のセット上の 2 次元オブジェクトのプロットデータは、XData プロパティと YData プロパティに含まれています。

例

すべて折りたたむ

データヒントを移動可能なウィンドウに表示

いくつかのデータをプロットして DataCursorManager オブジェクトを作成し、データカーソルモードを有効にします。DisplayStyle プロパティを 'window' に設定して、データヒントの内容を移動可能なウィンドウに表示します。次に、データ点をクリックしてデータヒントを作成します。データヒントウィンドウを移動するには、ウィンドウの見出しをクリックしてドラッグします。

x = linspace(0,5,30);
y = exp(x);
scatter(x,y)
dcm = datacursormode;
dcm.Enable = 'on';
dcm.DisplayStyle = 'window';

Scatter plot with one selected point. A window in the lower-right corner displays the coordinates of the selected point.

データヒントのテキストのカスタマイズ

DataCursorMode オブジェクトの UpdateFcn プロパティを設定して、データヒントのテキストをカスタマイズします。

まず、データヒント情報を受け入れてカスタマイズされたテキストを返すコールバック関数を定義します。UpdateFcn プロパティではコールバック関数の最初の引数は使用されないため、この引数を ~ に置き換えます。カスタマイズされたテキストを、この場合は座標の順序対を含む文字配列として返します。この関数を displayCoordinates.m というプログラムファイルとして保存します。

function txt = displayCoordinates(~,info)
    x = info.Position(1);
    y = info.Position(2);
    txt = ['(' num2str(x) ', ' num2str(y) ')'];
end

いくつかのデータをプロットしてデータカーソルモードを有効にし、UpdateFcn プロパティをコールバック関数に設定します。次に、データ点をクリックしてデータヒントを作成します。

x = 1:10;
y = x.^2;
scatter(x,y)

dcm = datacursormode;
dcm.Enable = 'on';
dcm.UpdateFcn = @displayCoordinates;

Scatter plot with one data tip. The text in the data tip is an ordered pair.

ヒント

一般に、データヒントには選択したデータ点の座標が表示されます。ただし、一部のタイプのチャートでは、データヒントに特殊な情報が表示されます。たとえば、関数 histogram を使用して作成したヒストグラムには、観測値の数とビンのエッジを箇条書きにしたデータヒントが表示されます。
データヒントをプログラムで作成およびカスタマイズするには、関数 datatip および dataTipTextRow を使用します。詳細については、カスタムデータヒントの作成を参照してください。

バージョン履歴

R2006a より前に導入

参考

dataTipInteraction | datatip

トピック

プロットデータの対話型の確認

datacursormode

説明

作成

構文

説明

入力引数

fig — ターゲット Figure Figure オブジェクト

プロパティ

SnapToDataVertex — 最も近いデータ点での表示 'on' (既定値) | 'off'

DisplayStyle — データ ヒントの表示スタイル 'datatip' (既定値) | 'window'

Interpreter — テキスト インタープリター 'tex' (既定値) | 'latex' | 'none'