グラフィックスオブジェクトのコールバックの作成

コールバックとは

"コールバック" は、グラフィックスオブジェクトをクリックしたり、Figure ウィンドウを閉じたりなどの、事前定義されたユーザーアクションへの応答として実行されるコマンドです。特定のユーザーアクションへの応答をプログラムするには、アクションを処理する "コールバック関数" を記述してから、その関数をユーザーアクションに関連付けられた "コールバックプロパティ" に割り当てます。たとえば、Figure の ButtonDownFcn コールバックを作成すれば、ユーザーが Figure をクリックしたときの応答をプログラムできます。

このトピックでは、Line、Axes、または Figure オブジェクトなどのグラフィックスオブジェクトのコールバックを記述する例を示します。特定のグラフィックスオブジェクトに関連付けられたコールバックの一覧については、そのオブジェクトのプロパティを参照してください。たとえば、Figure コールバックの一覧については、Figure のプロパティを参照してください。

アプリの UI コンポーネントのコールバックを記述する方法については、プログラムで作成したアプリ用のコールバックの作成を参照してください。

基本のコールバックの作成

グラフィックスコールバック関数は、少なくとも 2 つの入力引数を受け入れなければなりません。

コールバックを実行中のグラフィックスオブジェクト — コールバック関数内でこの引数を使用してオブジェクトを参照します。
イベントデータ構造体 — コールバック関数内でこの引数を使用して、コールバックプロパティおよびオブジェクトに固有のユーザーアクションに関する情報にアクセスします。多くのグラフィックスオブジェクトコールバックでは、この構造体は空です。

ユーザーアクションに応答してコールバックが実行されると、MATLAB^® でコールバック関数が呼び出され、これら 2 つの引数がその関数に渡されます。

コールバックを作成するには、最初に必須の入力引数を指定してコールバック関数を定義します。次に、関数ハンドルを関連のコールバックプロパティに割り当てます。

コールバック関数の定義

たとえば、figureCallback.m という名前の新しいファイルを作成し、figureCallback という名前のコールバック関数を定義します。ユーザーが figure ウィンドウでキーを押すと、コールバック関数がアクションを処理します。次の 2 つの入力引数を受け入れるコールバック関数を定義します。

src — 最初の引数を使用して、コールバックを実行中の特定の Figure を参照して、Figure でプロットされている Line オブジェクトを見つけます。
event — 2 つ目の引数を使用して、キーを押すユーザーアクションに関する特定の情報にアクセスします。押されたキーが + であればラインの幅を広げ、- であればラインの幅を狭めます。

function figureCallback(src,event)
line = findobj(src,"Type","Line");
if event.Character == "+"
    line.LineWidth = line.LineWidth+1;
elseif event.Character == "-"
    line.LineWidth = max(line.LineWidth-1,0.5);
end
end

コールバックプロパティへのコールバック関数の割り当て

コマンドウィンドウで、Figure オブジェクトを作成します。@ 演算子を使用して、関数ハンドルを Figure の WindowKeyPressFcn プロパティに割り当てます。ユーザーが Figure ウィンドウでキーを押すと、このコールバックが実行されます。次に、現在の Figure にデータをプロットします。

f = figure(WindowKeyPressFcn=@figureCallback);
plot(1:10)

コードを実行し、+ キーを押します。ラインの幅が広がります。

メモ

現在、キーボードベースのコールバックは、ライブエディターの Figure ではサポートされていません。詳細については、Figure のプロパティを参照してください。

追加の入力引数を使用するコールバックの作成

"無名関数" を使用して、追加の入力引数を使用するコールバックを作成できます。最初に、任意の数の入力引数を使用するコールバック関数を定義します。次に、MATLAB がコールバックに渡す必須のソース引数とイベント引数を受け入れる無名関数として関連のコールバックプロパティの値を指定してから、適切な入力を指定してコールバック関数を呼び出します。

メモ

現在、ライブエディターの Figure ではコールバックを無名関数として作成することはできません。

コールバック関数の定義

たとえば、ユーザーがマーカーをクリックしたときにマーカーエッジの色を変更し、コマンドウィンドウに x 座標と y 座標を表示するコールバック関数を定義します。displayCoordinates.m という名前の新しいファイルを作成し、displayCoordinates という名前のコールバック関数を定義します。次の 3 つの入力引数を受け入れるコールバック関数を定義します。

src — 最初の引数を使用して、コールバックを実行中の特定のグラフィックスオブジェクトを参照します。
~ — 2 つ目の引数に ~ 文字を指定して、この関数がコールバックイベントデータを使用しないことを示します。
ax — 3 つ目の引数を使用して、座標軸におけるマウスポインターの位置にアクセスします。

function displayCoordinates(src,~,ax)
src.MarkerEdgeColor = rand(1,3);
disp(ax.CurrentPoint(1,1:2))
end

コールバックプロパティへのコールバック関数の割り当て

コマンドウィンドウで、関数 scatter を使用して axes オブジェクト上にデータをプロットします。無名関数を使用して、Scatter オブジェクトの ButtonDownFcn コールバックプロパティを指定します。無名関数は、MATLAB がコールバックに渡す必須のソース引数とイベント引数を受け入れてから、必須の入力を指定して関数 displayCoordinates を呼び出します。

ax = axes;
x = randn(100,1);
y = randn(100,1);
scatter(x,y,"ButtonDownFcn",@(src,event)displayCoordinates(src,event,ax))

コードを実行し、マーカーをクリックします。マーカーエッジの色が変化し、コマンドウィンドウに x 座標と y 座標が表示されます。

詳細については、無名関数を参照してください。

無名関数は、ソース入力とイベント入力以外のコールバック入力引数を最も柔軟に指定できる方法ですが、代わりに cell 配列を使用してコールバックを指定する場合もあります。コールバック関数がソース入力とイベント入力の両方、およびその後に続く他の任意の引数を受け入れる場合、cell 配列を指定することで、コールバックを割り当てることができます。cell 配列の最初の要素はコールバック関数ハンドルであり、追加の要素はソースおよびイベントの後に関数に渡す入力です。

たとえば、代わりに cell 配列を使用して Scatter オブジェクトの ButtonDownFcn コールバックプロパティを指定できます。配列の最初の要素は関数 displayCoordinates のハンドルで、2 番目の要素はソース引数とイベント引数の後に関数 displayCoordinates に渡される axes オブジェクトです。

ax = axes;
x = randn(100,1);
y = randn(100,1);
scatter(x,y,"ButtonDownFcn",{@displayCoordinates,ax})

既定値としてのコールバックの作成

plot や bar などのプロット関数を呼び出すと、MATLAB では新しいグラフィックスオブジェクトが作成され、Figure や座標軸のほとんどのプロパティがリセットされます。そのため、特定のグラフィックスオブジェクトに定義したコールバック関数が MATLAB で削除される場合があります。代わりに特定のタイプの "すべて" のオブジェクトに対して実行されるコールバックを作成するには、ルートレベルでコールバック関数を既定として割り当てます。

コールバック関数の定義

customizeGrid という名前の関数を customizeGrid.m という名前の新しいファイルで定義します。関数は axes オブジェクトを受け取り、そのグリッドラインを表示およびカスタマイズします。

function customizeGrid(ax)
ax.XGrid = 'on';
ax.YGrid = 'on';
ax.GridLineStyle = '--';
ax.GridAlpha = 0.5;
end

コールバックプロパティへのコールバック関数の割り当て

groot オブジェクトに既定の座標軸の CreateFcn コールバックを設定すると、MATLAB で新しい axes オブジェクトが作成されるたびに、関数 customizeGrid が実行されます。2 つの必須のコールバック入力を受け取ってから、作成中の Axes オブジェクトに対して関数 customizeGrid を呼び出す無名関数としてプロパティを割り当てます。

set(groot,"defaultAxesCreateFcn",@(src,~)customizeGrid(src))

Figure に複数の座標軸を作成します。各座標軸のカスタマイズされたグリッドが表示されます。

ax1 = axes("Position",[0.1 0.1 0.8 0.35]);
ax2 = axes("Position",[0.1 0.55 0.8 0.35]);

詳細については、既定のプロパティ値を参照してください。

既定のコールバックの設定は、その MATLAB セッションに対して維持されます。すべての MATLAB セッションで既定のコールバックを設定するには、startup.m ファイルに既定値の割り当てを追加します。詳細については、startup を参照してください。