uispinner

スピナー コンポーネントの作成

構文

spn = uispinner

spn = uispinner(parent)

spn = uispinner(___,Name,Value)

説明

spn = uispinner は、スピナーを新しい Figure ウィンドウ内に作成し、Spinner オブジェクトを返します。MATLAB^® は関数 uifigure を呼び出してこの Figure を作成します。

spn = uispinner(parent) は、指定された親コンテナー内にスピナーを作成します。親には、関数 uifigure を使用して作成された Figure か、またはその子コンテナーのいずれかを指定できます。

spn = uispinner(___,Name,Value) は、1 つ以上の Name,Value のペアの引数を使用して、Spinner のプロパティを指定します。このオプションは、前述の構文のすべての入力引数の組み合わせで使用できます。

例

Figure ウィンドウにスピナーを作成

fig = uifigure;
spn = uispinner(fig);

パネルにスピナーを作成

パネル内にスピナーを作成します。

fig = uifigure;
pnl = uipanel(fig);
spn = uispinner(pnl);

スピナーのプロパティ値の設定とアクセス

アプリ ユーザーが入力できる値を 0 から 100 (上下限値を含む) に制限するスピナーを作成します。

スピナーを作成します。

fig = uifigure;
spn = uispinner(fig);

範囲を調べます。戻り値は、上下限値が制限されていないことを示します。

limits = spn.Limits

limits =

  -Inf   Inf

範囲を 0 から 100 に設定します。

spn.Limits = [0 100];

スピナーを作成して範囲の上下限値を含めるかどうかを指定

-5 より大きく 10 以下の値をアプリ ユーザーが入力できるスピナーを作成します。

fig = uifigure;
spn = uispinner(fig,'Limits', [-5  10],...
            'LowerLimitInclusive','off',...
            'UpperLimitInclusive','on',...
            'Value', 5);

コードを実行します。範囲外の値をスピナーに入力した場合、MATLAB は問題を示すメッセージを自動的に表示します。次に MATLAB は値を直前の有効な値に戻します。

厳密に 2 桁の小数部を使用して値を表示するスピナーを作成

アプリ ユーザーが任意の値を入力でき、ただし、必ず厳密に 2 桁の小数部を使用して値が表示されるスピナーを作成します。MATLAB はアプリ ユーザーが入力したそのままの値を格納することに注意してください。

fig = uifigure;
spn = uispinner(fig,'ValueDisplayFormat', '%.2f');

コードを実行してから、スピナーに 5.555 と入力します。スピナーの外側をクリックします。スピナーには 5.55 が表示されます。

MATLAB は元の値 5.555 を格納します。

スピナーをクリックすると、当初入力した値が表示されます。

変更後のスピナーの値に対するコードの応答

スピナーとスライダーを作成します。アプリ ユーザーがスピナーの値を変更すると、その値に一致するようにスライダーが更新されます。

MATLAB パス上の spinnerValue.m に次のコードを保存します。このコードは、スライダーとスピナーを含む Figure ウィンドウを作成します。アプリ ユーザーがスピナーの値を変更すると、ValueChangedFcn はスピナーの値を反映するようにスライダーを更新します。

function spinnervalue
fig = uifigure('Position',[100 100 370 280]);

sld = uislider(fig,...
    'Position',[90 220 120 3]);

spn = uispinner(fig,...
    'Position',[100 140 100 22],...
    'Limits',sld.Limits,...
    'ValueChangedFcn',@(spn,event) updateSlider(spn,sld));
end

% Create ValueChangedFcn callback
function updateSlider(spn,sld)
sld.Value = spn.Value;
end

spinnerValue を実行します。

スピナーの上矢印をクリックして押したままにし、値が 24 に達したら上矢印を離します。スライダーのつまみが移動してスピナーの値を示します。

変更中のスピナーの値に対するコードの応答

スピナーとスライダーを作成します。アプリ ユーザーがスピナーの値を変更しているとき、その値に一致するようにスライダーが繰り返し更新されます。

MATLAB パス上の showChangingValue.m に次のコードを保存します。このコードは、スライダーとスピナーを含む Figure ウィンドウを作成します。アプリ ユーザーがスピナーの値を変更しているとき、ValueChangingFcn はスピナーの値の変化に合わせて繰り返しスライダーを更新します。

function showChangingValue
fig = uifigure('Position',[100 100 370 280]);
sld = uislider(fig,...
    'Position',[90 220 120 3]);

spn = uispinner(fig,...
    'Position',[100 140 100 22],...
    'Limits',sld.Limits,...
    'ValueChangingFcn',@(spn,event) spinnerChanging(event,sld));
end

% Create ValueChangingFcn callback
function spinnerChanging(event,sld)
sld.Value = event.Value;
end

showChangingValue を実行します。

スピナーの上矢印をクリックして押したままにし、値が 24 に達したら上矢印を離します。スピナーの値の変化に従ってスライダーが移動します。

変更後のスピナーの値を計算するコードの応答

直前のスピナーの値と比較して値が増加しているか減少しているかを調べる ValueChangedFcn コールバックのコードを記述します。ランプの色を、値が増加しているときには緑、値が減少しているときには赤に設定します。

MATLAB パス上の upOrDown.m に次のコードを保存します。

function upOrDown
fig = uifigure(...
    'Position',[100 100 190 170]);

lmp = uilamp(fig,...
    'Position',[90 50 20 20],...
    'Color','green');

spn = uispinner(fig,...
    'Position',[50 100 100 22],...
    'ValueChangedFcn',@(spn,event) spinnerValueChanged(event,lmp));
end

% Create ValueChangedFcn that uses event data
function spinnerValueChanged(event,lmp)
newValue = event.Value;
previousValue = event.PreviousValue;
difference = newValue-previousValue;
if difference > 0
    lmp.Color = 'green';
else
    lmp.Color = 'red';
end
end

upOrDown を実行します。

スピナーの値を変更するたびに、ValueChangedFcn は値が増加しているか減少しているかを判別し、それに応じてランプの色を設定します。

入力引数

parent — 親コンテナー

Figure オブジェクト (既定値) | Panel オブジェクト | Tab オブジェクト | ButtonGroup オブジェクト | GridLayout オブジェクト

親コンテナー。関数 uifigure を使用して作成された Figure オブジェクト、またはその子コンテナー (Tab、Panel、ButtonGroup または GridLayout) のいずれかとして指定します。親コンテナーを指定しない場合、MATLAB は関数 uifigure を呼び出し、親コンテナーとして機能する新しい Figure オブジェクトを作成します。

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

例: 'Value',150 はスピナーに表示する数値 50 を指定します。

以下にリストするプロパティは、利用できるプロパティの一部です。完全なリストについては、Spinner のプロパティ を参照してください。

Value — スピナーの値

0 (既定値) | 数値

スピナーの値。数値として指定します。

アプリ ユーザーがスピナーに入力した値は文字ベクトルです。アプリ ユーザーが Enter キーを押すか、フォーカスを変更すると、アプリ ユーザーが入力した値が MATLAB により倍精度数に変換されます。

MATLAB は、次の場合に値を受け入れません。

• 文字ベクトルをスカラー数に変換できない場合。

• 値が NaN、空白または複素数である場合。

• 値が数式である場合 (例: 1+2)。

• 値が、Limits プロパティで指定された値の範囲外である場合。

MATLAB がアプリ ユーザーの入力値を受け取らない場合、値の要件を説明するツールヒントが表示されます。スピナーはただちに前の値に戻り、ValueChangedFcn は実行されません。

例: 10

データ型: double

ValueDisplayFormat — 値の表示形式

'%11.4g' (既定値) | 文字ベクトル | string スカラー

値の表示形式。文字ベクトルまたは string スカラーとして指定します。

MATLAB は sprintf を使用して、指定された形式を使用して値を表示します。

テキストと書式演算子を混在させることができます。以下に例を示します。

spin = uispinner('ValueDisplayFormat','%.0f MS/s');

結果としてスピナー コンポーネントは次のようになります。

アプリ ユーザーがスピナーのフィールドをクリックすると、フィールドにはテキストを除いた値が表示されます。

サポートされている書式演算子の詳細なリストについては、sprintf を参照してください。

RoundFractionalValues — 小数値の丸め

'off' (既定値) | on/off logical 値

アプリ ユーザーによって入力された小数値の丸め。'on' または 'off'、もしくは数値または logical 1 (true) または 0 (false) として指定します。'on' の値は true と等価であり、'off' は false と等価です。したがって、このプロパティの値を logical 値として使用できます。値は matlab.lang.OnOffSwitchState 型の on/off logical 値として格納されます。

• 'on' — 丸めの結果が有効な値になる場合、MATLAB は値を丸めて ValueChangedFcn コールバックを実行します。結果の値が Limits の上下の範囲外になる場合、MATLAB は Limits の範囲内の最も近い値に丸めてからコールバックを実行します。

• 'off' — MATLAB は小数値を 0 または正の整数に丸めません。

RoundFractionalValues プロパティ値がプログラムにより 'off' から 'on' に変更された場合、MATLAB は次の規則を適用します。

• 既存の値を丸めた結果の整数が Limits プロパティで指定された範囲内になる場合、MATLAB は既存の値を正方向に丸めます。

• 既存の値を丸めた結果の整数が下限値より小さくなる場合、MATLAB は既存の値を正方向に丸めます。

• 既存の値を丸めた結果の整数が上限値より大きくなる場合、MATLAB は既存の値を負方向に丸めます。

• 範囲内に有効な整数が存在しないように設定されている場合、MATLAB は RoundFractionalValues プロパティ値を 'off' に戻してエラー メッセージを表示します。

Step — 値をインクリメントまたはデクリメントする量

1 (既定値) | 数値スカラー

アプリ ユーザーが上下の矢印を押したときに、Value プロパティ値がそれぞれインクリメントまたはデクリメントする量。

Limits — スピナーの最小値と最大値

[-Inf Inf] (既定値) | 2 要素数値配列

スピナーの最小値と最大値。2 要素の数値配列として指定します。最初の値は、2 番目の値より小さくなければなりません。配列の要素を -Inf または Inf に設定すると、最小値または最大値がそれぞれ指定されません。

Limits を変更したことにより Value プロパティが新しい範囲の外になる場合、MATLAB は Value プロパティを新しい範囲内の値に設定します。たとえば、Limits プロパティが [0 100] で、Value プロパティが 20 だとします。Limits プロパティが [50 100] に変更された場合、MATLAB は Value プロパティを 50 に設定します (LowerLimitInclusive 値が 'on' であると仮定)。

例: [-Inf 200]

例: [-100 Inf]

例: [-100 200]

データ型: double

LowerLimitInclusive — 下限値を含めるかどうか

'on' (既定値) | on/off logical 値

下限値を含めるかどうか。'on' または 'off'、もしくは数値または logical 1 (true) または 0 (false) として指定します。'on' の値は true と等価であり、'off' は false と等価です。したがって、このプロパティの値を logical 値として使用できます。値は matlab.lang.OnOffSwitchState 型の on/off logical 値として格納されます。

• 'on' — 値は下限値以上でなければなりません。

• 'off' — 値は下限値より大きくなければなりません。

UpperLimitInclusive — 上限値を含めるかどうか

'on' (既定値) | on/off logical 値

上限値を含めるかどうか。'on' または 'off'、もしくは数値または logical 1 (true) または 0 (false) として指定します。'on' の値は true と等価であり、'off' は false と等価です。したがって、このプロパティの値を logical 値として使用できます。値は matlab.lang.OnOffSwitchState 型の on/off logical 値として格納されます。

• 'on' — 値は上限値以下でなければなりません。

• 'off' — 値は上限値より小さくなければなりません。

たとえば、数値入力を 0 から 1 まで (0 と 1 を除く) にする場合は、次のすべてを行います。

• Limits プロパティ値を [0 1] に設定します。

• UpperLimitInclusive プロパティを 'off' に設定します。

• LowerLimitInclusive プロパティを 'off' に設定します。

ValueChangedFcn — 値が変更されたときのコールバック

'' (既定値) | 関数ハンドル | cell 配列 | 文字ベクトル

値が変更されたときのコールバック。次の値のいずれかとして指定します。

• 関数ハンドル。

• 最初の要素が関数ハンドルである cell 配列。cell 配列内のその後の要素はコールバック関数に渡される引数です。

• 有効な MATLAB 式を含む文字ベクトル (非推奨)。MATLAB は、この式をベース ワークスペースで評価します。

このコールバックは、フォーカスを変更するか、スピナーの値の変更後に Enter キーを押すと実行されます。スピナーの値を変更するために値を入力するか矢印キーを押すかは関係ありません。このコールバックは、スピナーの値がプログラムにより変更される場合には実行されません。

このコールバック関数は、ユーザーのスピナー操作に関する特定の情報にアクセスできます。MATLAB は、この情報を ValueChangedData オブジェクトに格納して、2 番目の引数としてコールバック関数に渡します。App Designer では、引数は event と呼ばれます。ドット表記を使用して、オブジェクトのプロパティをクエリできます。たとえば、event.PreviousValue はスピナーの直前の値を返します。ValueChangedData オブジェクトは、文字ベクトルとして指定されているコールバック関数では使用できません。

次の表に、ValueChangedData オブジェクトのプロパティを示します。

プロパティ	値
Value	アプリ ユーザーによる最新操作の後のスピナーの値
PreviousValue	アプリ ユーザーによる最新操作の前のスピナーの値
Source	コールバックを実行するコンポーネント
EventName	'ValueChanged'

コールバックの記述の詳細については、App Designer のコールバックを参照してください。

ValueChangingFcn — 値が変更中のコールバック

'' (既定値) | 関数ハンドル | cell 配列 | 文字ベクトル

値が変更中のコールバック。次の値のいずれかとして指定します。

• 関数ハンドル。

• 最初の要素が関数ハンドルである cell 配列。cell 配列内のその後の要素はコールバック関数に渡される引数です。

• 有効な MATLAB 式を含む文字ベクトル (非推奨)。MATLAB は、この式をベース ワークスペースで評価します。

このコールバック関数は、スピナーの上矢印または下矢印をクリックしたままホールドすると実行されます。Value プロパティがプログラムにより変更される場合には実行されません。

このコールバック関数は、ユーザーのスピナー操作に関する特定の情報にアクセスできます。MATLAB は、この情報を ValueChangingData オブジェクトに格納して、2 番目の引数としてコールバック関数に渡します。App Designer では、引数は event と呼ばれます。ドット表記を使用して、オブジェクトのプロパティをクエリできます。たとえば、event.Value はスピナーの現在の値を返します。ValueChangingData オブジェクトは、文字ベクトルとして指定されているコールバック関数では使用できません。

次の表に、ValueChangingData オブジェクトのプロパティを示します。

プロパティ	値
Value	アプリ ユーザーが操作中のスピナーの現在の値
Source	コールバックを実行するコンポーネント
EventName	'ValueChanging'

Spinner の Value プロパティは、アプリ ユーザーが矢印キーを離すまで更新されません。したがって、矢印キーが押されている間の値を取得するには、ValueChangingData オブジェクトの Value プロパティをコードで取得しなければなりません。

メモ

Spinner オブジェクトの Value プロパティをそれ自体の ValueChangingFcn コールバック内から更新しないでください。予期しない動作を引き起こす可能性があります。ユーザー入力に応じてスピナーの値を更新するには、代わりに ValueChangedFcn コールバックを使用します。

コールバックは次のように実行されます。

• アプリ ユーザーがスピナーの上矢印または下矢印をクリックすると、コールバックが 1 回実行されます。たとえば、スピナーの値が 2 で、Step の値が 1 だとします。アプリ ユーザーが上矢印をクリックすると、コールバックが実行されます。

• アプリ ユーザーがスピナーの上矢印または下矢印を押したままにすると、コールバックが繰り返し実行されます。たとえば、アプリ ユーザーが上矢印をクリックして押したままにした場合、アプリ ユーザーが上矢印を離すまでコールバックが繰り返し実行されます。

コールバックの記述の詳細については、App Designer のコールバックを参照してください。

Position — スピナーの位置とサイズ

[100 100 100 22] (既定値) | [left bottom width height]

親コンテナーを基準にしたスピナーの位置とサイズ。ベクトル [left bottom width height] として指定します。次の表で、ベクトルの各要素について説明します。

要素	説明
left	親コンテナーの内側左端からスピナーの外側左端までの距離
bottom	親コンテナーの内側下端からスピナーの外側下端までの距離
width	スピナーの外側の右端と左端の間の距離
height	スピナーの外側の上端と下端の間の距離

すべての測定単位はピクセルです。

Position の値の基準は、親コンテナーの "描画可能領域" です。描画可能領域は、コンテナーの境界線の内側にある領域で、メニュー バーやタイトルなどの装飾が占める領域は含まれません。

例: [100 100 100 22]

バージョン履歴

R2016a で導入

参考

関数

• appdesigner | uifigure

プロパティ

• Spinner のプロパティ