datacursormode

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

説明

データカーソルモードを使用することで、データヒントを対話的に作成および編集してデータを探索できます。データヒントは、個々のデータ点に関する情報を表示する小さなテキストボックスです。関数 datacursormode を使用して、データカーソルモードの有効化または無効化と、その他の基本オプションの設定を行います。データヒントの外観と動作を制御するには、DataCursorManager オブジェクトを返して使用します。

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

また、既定で有効になっている組み込みの座標軸操作を使用して、対話的にデータを探索することもできます。たとえば、データ点で一時停止してデータヒントを一時的に表示したり、データ点をクリックしてデータヒントをピン留めしたりできます。組み込み操作では、操作モードを有効にする必要がなく、操作モードよりも応答が高速です。一方、データカーソルモードを有効にして、データヒントの動作をカスタマイズすることができます。組み込み操作の詳細については、チャートの対話機能の制御を参照してください。

作成

構文

datacursormode option

datacursormode

datacursormode(fig,option)

datacursormode(ax,option)

dcm = datacursormode

dcm = datacursormode(fig)

説明

datacursormode option は、現在の Figure 内のすべての座標軸について、データカーソルモードを設定します。たとえば、datacursormode on はデータカーソルモードを有効にし、datacursormode off はデータカーソルモードを無効にします。

データカーソルモードが有効になっている場合、カーソルかキーボードのいずれかを使用してデータヒントを作成します。

カーソル — プロットされたデータ点をクリックします。複数のデータヒントを作成するには、Shift キーを押したままデータ点を選択します。データヒントを別のデータ点に移動するには、そのデータヒントの位置にあるデータ点をドラッグします。
キーボード — 一部のチャートでは、現在選択されているデータヒントを別のデータ点に移動するには、上矢印 (↑) キー、下矢印 (↓) キー、左矢印 (←) キー、または 右矢印 (→) キーを押します。

一部の組み込み操作は、現在の操作モードに関係なく既定で有効になったままです。データカーソルモードに依存しない組み込みのデータヒント操作を無効にするには、関数 disableDefaultInteractivity を使用します。

datacursormode は、データカーソルモードの on と off を切り替えます。

datacursormode(fig,option) は、指定した Figure 内のすべての座標軸について、データカーソルモードを設定します。たとえば、Figure fig 内のすべての座標軸についてデータカーソルモードを有効にするには、datacursormode(fig,'on') を使用します。

datacursormode(ax,option) は、指定された座標軸についてデータカーソルモードを設定します。たとえば、座標軸 ax についてデータカーソルモードを有効にするには、datacursormode(ax,'on') を使用します。この構文は、App Designer で作成されたアプリ、および関数 uifigure を使用して作成されたアプリで使用します。 (R2023a 以降)

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

例

dcm = datacursormode(fig) は、指定された Figure に対して DataCursorManager オブジェクトを作成します。

入力引数

すべて展開する

`option` — データカーソルモードのオプション
`'on'` | `'off'` | `'toggle'`

データカーソルモードのオプション。次の値のいずれかとして指定します。

'on' — データカーソルモードを有効にします。
'off' — データカーソルモードを無効にします。一部の組み込み操作は、現在の操作モードに関係なく既定で有効になったままです。データカーソルモードに依存しない組み込みのデータヒント操作を無効にするには、関数 disableDefaultInteractivity を使用します。
'toggle' — データカーソルモードを切り替えます。たとえば、データカーソルモードが無効になっている場合、'toggle' はデータカーソルモードを有効にします。このオプションを使用することは、引数を指定せずに datacursormode を呼び出すことと同じです。

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

ターゲット Figure。Figure オブジェクトとして指定します。ターゲット Figure を指定すると、現在または将来のすべての Axes の子にモードが設定されます。

`ax` — ターゲット座標軸
`Axes` オブジェクト

ターゲット座標軸。Axes オブジェクトとして指定します。

プロパティ

すべて展開する

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

データカーソルモードの状態。'on' または 'off'、もしくは数値または logical の 1 (true) または 0 (false) として指定します。'on' の値は true と等価であり、'off' は false と等価です。したがって、このプロパティの値を logical 値として使用できます。値は OnOffSwitchState 型の on/off logical 値として格納されます。

`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/) を参照してください。

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

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

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

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

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

コールバックの詳細については、グラフィックスオブジェクトのコールバックの作成を参照してください。

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

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

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

オブジェクト関数

getCursorInfo

関数 getCursorInfo は、Figure 内の各データヒントのターゲットと座標を返します。

データカーソルマネージャーオブジェクト dcm に対して info = getCursorInfo(dcm) を呼び出すと、以下のフィールドをもつベクトル info が返されます。

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

例

すべて折りたたむ

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

いくつかのデータをプロットして DataCursorManager オブジェクトを作成します。

x = linspace(0,5,30);
y = exp(x);
scatter(x,y)
dcm = datacursormode;

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

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.

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

データヒント情報を受け入れてカスタマイズされたテキストを返すコールバック関数を定義します。カスタマイズされたテキストを、この場合は座標の順序対を含む string として返します。この関数を displayCoordinates.m という名前のプログラムファイルとして保存します。

function txt = displayCoordinates(~,info)
    x = info.Position(1);
    y = info.Position(2);
    myDatatipText = "(%s, %s)";
    txt = sprintf(myDatatipText, 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 より前に導入

すべて展開する

R2023a: アプリでの指定した座標軸に対するデータカーソルモードの設定

App Designer で作成されたアプリ、および関数 uifigure を使用して作成されたアプリで、datacursormode の最初の入力として座標軸を指定して、座標軸にデータカーソルモードを設定します。座標軸にデータカーソルモードを設定する場合、関数は DataCursorManager オブジェクトを返しません。

R2018b: 既定で有効になっているデータヒントを使用したデータの探索

既定で有効になっている組み込みの座標軸操作を使用して、対話的にデータを探索します。たとえば、データカーソルモードを有効にしなくても、データ点で一時停止してデータヒントを表示することができます。詳細については、チャートの対話機能の制御を参照してください。

以前は、既定で有効になっている座標軸操作はありませんでした。

参考

関数

dataTipInteraction | datatip

datacursormode

説明

作成

構文

説明

入力引数

option — データ カーソル モードのオプション 'on' | 'off' | 'toggle'

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

ax — ターゲット座標軸 Axes オブジェクト

プロパティ

Enable — データ カーソル モードの状態 'off' (既定値) | 'on' | on/off logical 値

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

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

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

TeX マークアップ

LaTeX マークアップ

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

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

オブジェクト関数

例

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

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

ヒント

代替機能

座標軸ツール バー

プログラミングのワークフロー

バージョン履歴

R2023a: アプリでの指定した座標軸に対するデータ カーソル モードの設定

R2018b: 既定で有効になっているデータ ヒントを使用したデータの探索

参考

関数

トピック

`option` — データカーソルモードのオプション
`'on'` | `'off'` | `'toggle'`

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

`ax` — ターゲット座標軸
`Axes` オブジェクト

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

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

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

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

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

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

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

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

座標軸ツールバー

R2023a: アプリでの指定した座標軸に対するデータカーソルモードの設定

R2018b: 既定で有効になっているデータヒントを使用したデータの探索