Main Content

datacursormode

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

説明

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

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

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

作成

説明

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

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

  • カーソル — プロットされたデータ点をクリックします。複数のデータ ヒントを作成するには、Shift キーを押したままデータ点を選択します。データ ヒントを別のデータ点に移動するには、そのデータ ヒントの位置にあるデータ点をドラッグします。

  • キーボード — 一部のチャートでは、現在選択されているデータ ヒントを別のデータ点に移動するには、上矢印 (↑) キー、下矢印 (↓) キー、左矢印 (←) キー、または 右矢印 (→) キーを押します。

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

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

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 オブジェクトを作成します。

入力引数

すべて展開する

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

  • 'on' — データ カーソル モードを有効にします。

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

  • 'toggle' — データ カーソル モードを切り替えます。たとえば、データ カーソル モードが無効になっている場合、'toggle' はデータ カーソル モードを有効にします。このオプションを使用することは、引数を指定せずに datacursormode を呼び出すことと同じです。

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

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

プロパティ

すべて展開する

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

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

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

  • 'off' — データ点の間であっても、クリックした位置にデータ ヒントを表示します。

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

  • 'datatip' — データ ヒントをデータ値に付加される小さいテキスト ボックスとして表示します。複数のデータ ヒントを作成するには、Shift キーを押したままデータ点を選択します。データ カーソル モードを無効にしても、既存のデータ ヒントはチャートに残ります。

  • 'window' — データ ヒントを Figure 内の移動可能なウィンドウに表示します。表示スタイルが 'window' の場合、一度に表示できるデータ ヒントは 1 つだけです。データ カーソル モードを無効にすると、ウィンドウが閉じます。

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

  • '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 を、redgreenyellowmagentablueblackwhitegraydarkGreenorangelightBlue の色のいずれかに置き換えます。'\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/) を参照してください。

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

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

  • empty — 空の引数。これが使用されないことを示すには、関数の中でこれをチルダ文字 (~) に置き換えます。

  • info — データ ヒントに関する情報を含む構造体。info 引数には TargetPosition の 2 つのフィールドがあります。Target フィールドには DataTipTemplate プロパティをもつオブジェクトが含まれます。Position フィールドにはデータ ヒントの座標が含まれます。

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

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

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

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

オブジェクト関数

getCursorInfo

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

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

  • TargetDataTipTemplate プロパティをもつオブジェクト (LineHistogramSurfaceFunctionLine など)。

  • Position — データ ヒントの座標。座標の解釈は、座標軸のタイプによって異なります。たとえば、直交座標軸の座標は、データと同じ単位の xy および 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.

データ ヒント情報を受け入れてカスタマイズされたテキストを返すコールバック関数を定義します。カスタマイズされたテキストを、この場合は座標の順序対を含む文字配列として返します。この関数を 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 より前に導入

すべて展開する