dialogs — 簡単に使えるユーザーインターフェイスダイヤログ
dialogs モジュールは、iOS上でのシンプルなデータ入力のための簡単に使えるGUI(Graphics User Interface)ダイアログを提供します。多くの場合、ui モジュールの先頭に配置します。ui を直接使用するのに比べて自由度は低くなりますが、より簡単に使用でき、多くの場合、数行の短いスクリプトを書くだけで済みます。
概 要
このモジュールの大部分の関数は、ダイアログを表示し、ユーザーの入力を返します。以下の各種のダイアログをサポートしています：
- 複数の入力行を持つ文字入力ダイアログ。フォントといくつかのキーボード属性(オートコレクト機能など)をカスタマイズ可能です。(text_dialog() を参照)
- アイテムのリストから選択するリストダイアログ。アイテムリストの中から一つないし複数を選択できます。(list_dialog() を参照)
- 同じくアイテムのリストを表示しますが、アイテムのリストを選択するのではなく、ユーザーが順番を変えたり削除したりできる編集リストダイアログ。(edit_list_dialog() を参照)
- 日付/時刻ダイアログ。日付、時刻またはその双方を選べるデイトピッカーのほか、例えばタイマーに使うようなカウントダウン/継続時間のモードもあります。(date_dialog(), time_dialog(), datetime_dialog(), duration_dialog() を参照)
- カスタマイズできるデータ入力エリアのリストを持つフォームダイアログ。データ入力エリアにはブール値を得るためのスイッチや、文字列を得るためのテキスト/電子メール/パスワード用エリア、デイトピッカー、複数の選択リストを得るためのチェックマークを配置することができます。このダイアログは一番フレキシブルなタイプのダイアログですが、その一方で多くの項目を設定する必要があります。(see form_dialog() を参照)
ダイアログ関数
dialogs.list_dialog(title='', items=None, multiple=False)
アイテムのリストを表示し、選ばれたものを返します。ダイアログがキャンセルされた場合には、Noneを返します。
引数 title にはダイアログの最上段に表示するタイトルを設定します。
引数 item にはアイテムのリストを設定します。アイテムのリストは文字列に変換できるオブジェクトであればどんな種類のものでも使用可能です。リストとして表示されたどのアイテムでもより簡便に処理できるよう、ディクショナリー型のリストを使うこともできます。
引数 multiple を True にすれば、複数のアイテムを選択することができます。(詳細は ui.ListDataSource.items を参照)
（例 dialog.list_dialog(title='選んで下さい',items=('選択肢1','選択肢2'),multiple=False) ）
dialogs.edit_list_dialog(title='', items=None, move=True, delete=True)
ユーザーが順番変更をすることが可能なアイテムのリストを表示します。デフォルトでは、リストの中のアイテムの順番を変えるだけでなく、アイテムの削除も可能です。これについては、引数 move と delete で設定できます。
なお、引数 title にはダイアログの最上段に表示するタイトルを設定します。
返ってくる値は、修正されたアイテムのリストです。ただし、ダイアログがキャンセルされた場合にはNoneが返されます。
（例 dialogs.edit_list_dialog(title='順序変更や削除が可能です',items=[1,2,3],move=True,delete=True)
dialogs.form_dialog(title='', fields=None, sections=None)
多くの設定を要するインターフェイスと同様の、フォームダイアログを表示します。
ダイアログのそれぞれのエリアはディクショナリー型で定義します。エリアが一つしかない場合は、引数 field に設定するディクショナリーを省略することができます。複数のセクションが必要な場合には、タプルで指定します。通常は、セクションのタイトルと、そのエリアのリストの２つのタプルとなります。セクションのフッターの文字を入れる場合には、オプションとして3番目のアイテムとして追加できます。
この関数の戻り値は、それぞれのフィールドの値のディクショナリー型になります。ただし、ダイアログがキャンセルされた場合には、Noneが返されます。
フィールドを指定するディクショナリーは、以下のキー項目を含む必要があります：
- 'type' – (必須項目) フィールドのタイプを指定します。'switch', 'text', 'url', 'email', 'password', 'number', 'check', 'datetime', 'date', そして'time'のいずれかにする必要があります。
- 'key' – フォームからの戻り値の中のフィールドのキーを指定します。
- 'value' – フィールドの初期値を指定します。text/url/email/password/numberのフィールドの場合は文字列を指定します。 switch フィールドの場合にはブール値(True/False)を、datetimeフィールドの場合には datetime オブジェクトでなければなりません。
- 'title' – ユーザーが読みやすいように、フィールドにつけるタイトル/ラベルを指定します。
'type' だけが必須のキーです。もし'key' が省略されている場合には、'title' が代わりに使用されます。両方とも無い場合には、戻り値のディクショナリーでは、フィールドに連番が振られることになります。
全てのフィールドタイプにはオプションとして以下のキーが指定できます。
- 'tint_color' – フィールド上のパーツの色（tint colot）を指定します。指定の効果については、フィールドのタイプにより異なります。
- 'icon' – システムに組み込まれている画像や ui.Image オブジェクトの名前を指定します。
text/url/email/password/number のフィールドではオプションとして以下のキーが指定できます：
- 'placeholder' – フィールドが空の時に表示する文字を指定します。
- 'autocorrection' – フィールドでの入力に対してオートコレクトを適用するか否かをブール型(True/False)で指定します。
- 'autocapitalization' – テキスト型のフィールドの場合に自動で大文字化します。どのような値が指定できるかは、 ui.TextField.autocapitalization_type を参照して下さい。
(例）
import dialogs
import datetime
sections = []
fields = []
field = {'type':'switch','key':'chrc1','value':False,'title':'スイッチをスライド→','tint_color':'pink'}
fields.append(field)
sections.append(('Switchだけのセクション', fields))
dt = datetime.datetime.strptime('2021-10-20 20:10:30','%Y-%m-%d %H:%M:%S')
dt2 = datetime.datetime.strptime('2021-10-25','%Y-%m-%d')
fields = [
{'type':'text','key':'chrc2','placeholder':'ここに入力','title':'文字を入力:','tint_color':'yellow'},
{'type':'url','key':'chrc3','value':'https://www.yahoo.co.jp/','title':'URL:','tint_color':'yellow'},
{'type':'email','key':'chrc4','value':'hoge@yahoo.co.jp','title':'E-mail:','tint_color':'linen'},
{'type':'password','key':'chrc5','value':'secret','title':'Password:','tint_color':'linen'},
{'type':'number','key':'chrc6','value':'10','title':'Number','tint_color':'red'},
{'type':'check','key':'chrc7','value':False,'title':'check','tint_color':'purple'},{'type':'datetime','key':'chrc8','value':dt,'title':'datetime:','tint_color':'red'},
{'type':'date','key':'chrc9','value':dt2,'title':'date:','tint_color':'bule'}]
sections.append(('残り全部盛りのセクション', fields))
dialogs.form_dialog(title='全体タイトル',sections=sections)
dialogs.text_dialog(title='', text='', font=('<system>', 16), autocorrection=None, autocapitalization=ui.AUTOCAPITALIZE_SENTENCES, spellchecking=None)
複数行のテキストを編集できるシートを表示します。
エディターの挙動は、autocorrection や autocapitalization、spellcheckingparametersで指定できます。引数 text でエディターに最初に表示するテキストを指定します。
編集されたテキストは、文字列として返されます。なお、ダイアログがキャンセルされた場合には、代わりに None が返されます。
dialogs.date_dialog(title='')
ディト・ピッカー（日付指定）ダイアログを表示します。戻り値は datetime.datetime オブジェクトです。
dialogs.time_dialog(title='')
タイム・ピッカー（時刻指定）ダイアログを表示します。戻り値はdatetime.datetime オブジェクトです。
dialogs.datetime_dialog(title='')
デイト/タイム・ピッカー（日付時刻指定）ダイアログを表示します。戻り値はdatetime.datetime オブジェクトです。
dialogs.duration_dialog(title='')
カウントダウンタイマーに使われるような残り時間ピッカーを表示します。選択した残り時間を秒単位で返します。（例 1分であれば60.0を返します）
シェア
dialogs.share_image(img)
引数 img の画像（ui.image と PIL Image のどちらでも可）をシェアするダイアログを表示します。
dialogs.share_text(text)
引数 text の文字列をシェアするダイアログを表示します。
dialogs.share_url(url)
引数 URL をシェアするダイアログを表示します。
ファイルのインポート
dialogs.pick_document(types=['public.data'])
ファイル読込のためのファイル名ピッカー画面を表示し、ユーザーが選択したファイルのパスを返します。ダイアログがキャンセルされた場合にはNone を返します。
引数 types は、ファイル名ピッカーで選択可能な Universal Type Identifiers(UTIs) で設定する必要があります。デフォルト値として、['public.data'] は全ての一般的なファイル選択が可能なように設定されています。システムで定義された UTIs のリストは、アップルの Uniform Type Identifiers Reference で確認できます。
戻り値は現在の（テンポラリー）ファイルです。直接読むことができますが、長期にコピーを保存したい場合には、別の場所に移動する必要があります。
警告機能を持つ関数
これらの関数は console モジュールからインポートされています.
dialogs.alert()
console.alert() を参照