javax.microedition.lcdui
クラス Alert

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Screen
          javax.microedition.lcdui.Alert

public class Alert
extends Screen

Alert は次に続く Displayable の前にデータをユーザに提示して、一定時間待つスクリーンです。 Alert はテキスト文字列とイメージを含むことができます。 Alert の意図する使用方法はエラーや他の例外的な状態をユーザーに対して通知することです。

アプリケーションが Alert に対して setTimeout(Alert.FOREVER) を呼び出すと、Alert はモーダル化し無期限に表示を行い、ユーザーによる"撤去"を待つようになります。ユーザーが"撤去"を指示すると、まるでタイムアウトが訪れたかのようにすぐに次の Displayable を表示します。

アプリケーションが Alert に対してタイムアウト時間を設定したとしても、Alert に対して多くの表示内容を与えたため、全ての表示にスクロールが必要となる場合は Alert は自動的にモーダル化します。

Alert には、Alert の種類に対する意味を提供するために AlertType を関連付けることができます。 実装は Alert をユーザーに提示する際に、適切な音を発生させるためにこのタイプを使用することができます。 参照： AlertType.playSound()

Alert は任意の Image を含むことができます。 Image には可変および不変タイプがあります。 Image が可変タイプの場合、Alert はこの Image がコンストラクタあるいは setImage に渡された際のスナップショットを構築してそれを使用します。 Alert が表示される際には常にこのスナップショットを内容として用います。 アプリケーションが呼び出し時の Image オブジェクトに対して描画を行ったとしても、次の setImage の呼び出しまでスナップショットの更新は行われません。 Alert がカレントにあるか表示状態の場合にはスナップショットによる画面の更新は行われません（これはアプリケーションが、正確にいつ Displayable が表示されて、いつディスプレイから消えるかコントロールすることができないためです）。

アクティブ・インジケータ

Alert はアクティブまたはプログレス・インジケータとして使用する、任意の Gauge オブジェクトを設定することができます。 デフォルトでは、Alert にはアクティブ・インジケータは存在しません。 setIndicator(javax.microedition.lcdui.Gauge) メソッドで設定することができます。 アクティブ・インジケータとして使用する Gauge オブジェクトは以下の制限の全てに合致しなければなりません。

• 非対話型でなければなりません。
• 別のコンテナ（Alert または Form）に対して未設定でなければなりません。
• １つも Command が設定されていてはなりません。
• ItemCommandListener が設定されてはなりません。
• ラベルが設定されていてはなりません（つまりラベルは null でなければなりません）。
• 好ましいとする幅と高さの設定のいずれもアンロック状態でなければなりません。
• レイアウト値は LAYOUT_DEFAULT でなければなりません。

これらの制限のいずれかに違反する Gauge オブジェクトの使用を試みるのはアプリケーションの誤りです。 Gauge オブジェクトがインジケータとして Alert において使用されている最中に、アプリケーションがこれらの Gauge オブジェクトの状態を変更することは避けなければなりません。

コマンドとリスナー

他の Displayable クラスの様に、Alert は Command を設定することができ、アプリケーションが設定した CommandListener に通知することができます。 Alert クラスはコマンドとリスナーのために特殊な振る舞いを加えます。

Alert が作成されると、暗黙のうちに特殊なコマンドである DISMISS_COMMAND を自身に設定します。 アプリケーションが Alert に対して他の Command を加えると、暗黙のうちに DISMISS_COMMAND を自身から削除します。 アプリケーションが他の Command を全て Alert から削除すると、再び暗黙のうちに DISMISS_COMMAND を自身に設定します。 明示して DISMISS_COMMAND を加えるか削除する試みは無視されます。 したがって Alert には常に少なくとも１つのコマンドが設定されています。

Alert に２つ以上の Command があれば、自動的に Alert はモーダル化し、タイムアウト値は FOREVER になります。 Command が呼び出されるまで、Alert は表示されつづけます。 Alert に１つの Command（それが DISMISS_COMMAND かアプリケーションが設定したもののいずれでも）がある場合は、上記で説明した振る舞いを Alert に行います。 タイムアウトが発生すると、まるでユーザーが明示して Command を呼び出したのと同様の効果を持ちます。

Alert が生成されると、暗黙のうちに関連付けられたデフォルト・リスナーが呼ばれるように自身に設定します。 アプリケーションが提供するリスナーを setCommandListener(javax.microedition.lcdui.CommandListener) メソッドにて後任のリスナーとして設定することができます（置き換えられます）。 アプリケーションが null を setCommandListener(javax.microedition.lcdui.CommandListener) メソッドに渡し、リスナーを削除すると暗黙のうちにデフォルト・リスナーを再設定します。

Display.setCurrent(Alert, Displayable) メソッドおよび Display.setCurrent(Displayable) メソッドは Alert が撤去された後に自動的に他の Displayable を表示するための特殊な振る舞いを定義します。 Alert が撤去されるか、あるいはコマンドが呼び出され、デフォルト・リスナーが Alert に設定されている場合に限り、この特殊な振る舞いが発生します。 ユーザーが Command を呼び出した時にデフォルト・リスナーが設定されているなら、デフォルト・リスナーは Command を無視して自動遷移する振る舞いを行います。

アプリケーションが自身の CommandListener を設定した場合には、自動遷移の振る舞いは無効になります。 リスナーのコードが別の Displayable に遷移する責任を持たなければなりません。 アプリケーションがリスナーを設定した場合、Command はリスナーの commandAction メソッドを呼び出して通知します。 通知された Command は現在 Alert に設定されている Command のうちの１つになります： DISMISS_COMMAND あるいはアプリケーションが設定した Command の中の１つのいずれか。

アプリケーションは null を setCommandListener メソッドに渡すことにより、デフォルトのリスナーに戻すことができます。

注意：アプリケーションは Alert に対して Ticker を Displayable.setTicker メソッドで設定することができますが、実装上の制限によりそれを表示することができないことがあります。

導入されたバージョン:

MIDP 1.0

関連項目:

AlertType

FOREVER

public static final int FOREVER

FOREVER は、ユーザーが Alert の撤去を命じるまで表示することを示します。 Alert をモーダル表示することを示すために setTimeout(int) メソッドを呼び出す際のパラメータとして使用します。 モーダルの Alert は次の Displayable を表示する前に、指定された時間待つ代わりにユーザーがボタンを押すなどのような何らかの明確な行動を取るのを待ちます。

FOREVER の値は -2 です。

関連項目:

setTimeout(int), 定数フィールド値

DISMISS_COMMAND

public static final Command DISMISS_COMMAND

この Command は Alert が撤去することを示すためにリスナーに通知されます。 この Command は暗黙に存在し、Alert に他の Command が設定されていない場合のみ通知されます。 DISMISS_COMMAND のフィールド値は以下の通りです：

• ラベル = ""（空文字列）
• タイプ = Command.OK
• 優先度 = 0

アプリケーションから見えるラベル値は上記の通りです。 しかし、実装は実装特有のラベルを使用することで、ユーザーに DISMISS_COMMAND を表示することができます。

Alert に対して DISMISS_COMMAND の追加及び削除を試みても効果はありません。 しかし、他の Displayable と共に使用する場合には普通の Command として取り扱われます。

導入されたバージョン:

MIDP 2.0

Alert

public Alert(String title)

指定されたタイトルを持った空の Alert オブジェクトを構築します。 title に null が指定された場合、タイトルは指定されなかったものとして処理を行います。

このコンストラクタの呼び出しは以下の記述と等価です。

     Alert(title, null, null, null);

パラメータ:

title - 設定するタイトル文字列あるいは null を渡します。

関連項目:

Alert(String, String, Image, AlertType)

Alert

public Alert(String title,
             String alertText,
             Image alertImage,
             AlertType alertType)

指定されたタイトル、メッセージ文字列、イメージおよび AlertType を設定した Alert オブジェクトを構築します。 メッセージ文字列および Image の表示レイアウトは実装に依存します。 デフォルトの表示期間は getDefaultTimeout() が返すのと等価の設定がなされます。 指定された Image は可変および不変タイプのいずれでもかまいません。 特定の alertType の取り扱いと動きは AlertType で説明しています。 alertType パラメータの値として null が許容されており、Alert は特定の規定されたタイプには属さないことを示します。 DISMISS_COMMAND は新しい Alert における唯一の Command です。 新しい Alert に関連する CommandListener はデフォルト・リスナーです。 振る舞いに関する詳細はコマンドとリスナー・セクションで説明しています。

パラメータ:

title - タイトル文字列あるいは null を渡します。

alertText - メッセージ文字列あるいは null を渡します。

alertImage - 表示する Image オブジェクトあるいは null を渡します。

alertType - 構築する Alert の種類を決める AlertType オブジェクトあるいは null 渡します。

getDefaultTimeout

public int getDefaultTimeout()

この実装における Alert オブジェクトのデフォルト表示期間をミリ秒単位で返します。 返す値は正数あるいは FOREVER と等価の値です。FOREVER は Alert がデフォルトでモーダルであることを示します。 返す値は実装によって異なり、それぞれ適切になるように設定されています。

戻り値:

デフォルトの表示期間をミリ秒単位で、あるいは FOREVER を返します。

関連項目:

FOREVER, getTimeout(), setTimeout(int)

getTimeout

public int getTimeout()

この Alert オブジェクトに設定されている表示期間をミリ秒単位で返します。 返す値は正数あるいは FOREVER と等価の値です。FOREVER は Alert がモーダルであることを示します。 この値は setTimeout(int) メソッドによってアプリケーションが設定した値と必ずしも同じ値ではありません。 表示内容がスクロールを必要とするほどに多いために Alert がモーダル化されると、getTimeout が返す値は FOREVER になります。

戻り値:

設定されている表示期間がミリ秒単位で、あるいは FOREVER を返します。

関連項目:

FOREVER, getDefaultTimeout(), setTimeout(int)

setTimeout

public void setTimeout(int time)

この Alert の表示期間をミリ秒単位で設定します。

表示期間として設定できる値は正数あるいは FOREVER 定数のいずれかです。

パラメータ:

time - 設定する表示期間あるいは FOREVER 定数を渡します。

例外:

IllegalArgumentException - time に正数でなく、FOREVER 定数でもない値を渡した場合に throw します。

関連項目:

FOREVER, getDefaultTimeout(), getTimeout()

getType

public AlertType getType()

設定されているタイプ（AlertType オブジェクト）を返します。 この Alert オブジェクトに AlertType が設定されていない場合は null を返します。

戻り値:

設定されている AlertType オブジェクトあるいは null を返します。

関連項目:

setType(javax.microedition.lcdui.AlertType)

setType

public void setType(AlertType type)

新しいタイプ（AlertType オブジェクト）を設定します。 表示する Alert の種類は type によって渡される AlertType オブジェクトによって決定します。 現在設定されているタイプを削除する場合は null を渡します。

パラメータ:

type - 設定する AlertType オブジェクトあるいは null を渡します。

関連項目:

getType(), AlertType.INFO, AlertType.WARNING, AlertType.ERROR, AlertType.ALARM, AlertType.CONFIRMATION

getString

public String getString()

設定されているメッセージ文字列を返します。 この Alert オブジェクトにメッセージが設定されていない場合は null を返します。

戻り値:

設定されているメッセージ文字列あるいは null を返します。

setString

public void setString(String str)

表示するメッセージ文字列を設定します。 現在設定されているメッセージ文字列を削除する場合は null を渡します。

Alert が表示されている最中に setString を呼び出すと、実装は表示の更新が可能になり次第すぐに新しい表示内容に更新します。

パラメータ:

str - 設定するメッセージ文字列あるいは null を渡します。

getImage

public Image getImage()

設定されている Image オブジェクトを返します。 Image オブジェクトが設定されていない場合は null を返します。

戻り値:

設定されている Image オブジェクトあるいは null を返します。

setImage

public void setImage(Image img)

表示する Image オブジェクトを設定します。 現在設定されている Image オブジェクトを削除する場合は null を渡します。 img が可変タイプならば、スナップショットを構築してそれを使用します。 Alert が表示される際には常にこのスナップショットを内容として用います。 img が既にこの Alert に設定されている Image ならば、まるで新しい Image であるかのように img のスナップショットを作成します。 したがって、Alert に含まれる可変タイプのイメージに描画を行った後、アプリケーションは以下のような呼び出しを行います。

alert.setImage(alert.getImage());

これにより Alert のスナップショットがリフレッシュされます。

Alert が表示されている最中に setImage を呼び出すと、実装は表示の更新が可能になり次第すぐに新しい表示内容に更新します。

パラメータ:

img - 表示する Image オブジェクトあるいは null を渡します。

setIndicator

public void setIndicator(Gauge indicator)

この Alert にアクティブ・インジケータを設定します。 アクティブ・インジケータは Gauge オブジェクトです。 Alert のアクティブ・インジケータとして使用するために、それは制限に合致する状態でなければなりません。 制限の内容は上に記載があります。

もしも indicator が null であれば、現在設定されているアクティブ・インジケータを削除します。

パラメータ:

indicator - この Alert に設定するアクティブ・インジケータ、またはインジケータを取り除く場合には null を渡します。

例外:

IllegalArgumentException - indicator が Alert で使用するための制限を満たしていない場合に throw します。

導入されたバージョン:

MIDP 2.0

関連項目:

getIndicator()

getIndicator

public Gauge getIndicator()

この Alert に設定されているアクティブ・インジケータを取得します。

戻り値:

この Alert に設定されているアクティブ・インジケータの参照、あるいは設定されていなければ null を返します。

導入されたバージョン:

MIDP 2.0

関連項目:

setIndicator(javax.microedition.lcdui.Gauge)

addCommand

public void addCommand(Command cmd)

Displayable.addCommand(javax.microedition.lcdui.Command) のように Command を追加します。 また、アプリケーションが Alert に対して最初の Command を追加する際に、暗黙のうちに DISMISS_COMMAND を削除します。 このメソッドの呼び出しパラメータに DISMISS_COMMAND が指定された場合、何も処理を行いません。

オーバーライド:

クラス Displayable 内の addCommand

パラメータ:

cmd - 追加する Command オブジェクトを渡します。

例外:

NullPointerException - cmd が null の場合に throw します。

removeCommand

public void removeCommand(Command cmd)

Displayable.addCommand(javax.microedition.lcdui.Command) のように Command を削除します。 また、アプリケーションが Alert に対して最後の Command を削除する際に、暗黙のうちに DISMISS_COMMAND を追加します。 このメソッドの呼び出しパラメータに DISMISS_COMMAND が指定された場合、何も処理を行いません。

オーバーライド:

クラス Displayable 内の removeCommand

パラメータ:

cmd - 削除する Command オブジェクトを渡します。

導入されたバージョン:

MIDP 2.0

setCommandListener

public void setCommandListener(CommandListener l)

Displayable.setCommandListener(javax.microedition.lcdui.CommandListener) のように CommandListener を設定します。 しかし、以下に示す追加の処理を行います。 もし、リスナーのパラメータが null ならば、デフォルト・リスナーを設定します。 デフォルト・リスナーの振る舞いの定義に関してはコマンドとリスナーを参照してください。

オーバーライド:

クラス Displayable 内の setCommandListener

パラメータ:

l - 設定する CommandListener オブジェクトあるいは null を渡します。