More than 3 years have passed since last update.

マイコン用GUIライブラリ emWin Graphical API6

Posted at 2021-01-17

ウィンドウ・マネージャ

6.1

ウィンドウ

ウインドウは四角形です．左上をX，Y座標で原点として持ち，幅と高さも持っています．次の特徴があります．
・四角形
・Z位置を持つ
・隠したり表示したりできる
・有効/無効領域の切り替え
・透明なコンポーネントもある
・コールバック関数を呼べるコンポーネントもある

アクティブ・ウィンドウ

　今現在，描画できる状態のウィンドウをアクティブ・ウィンドウ(Active window)と呼びます．これは必ずしも最前面のウィンドウではありません．

コールバック関数

　イベント駆動でユーザ・プログラムに用意したコールバック関数を呼び出せます．これらの関数ではグラフィック・システムの特定機能を呼び出せます．通常GUIは自動的に再描画されます．

子ウィンドウ

　子ウィンドウ(Child window)は，親ウィンドウに関連図けられたものです．親ウィンドウが動いた場合，子ウィンドウも連動します．子ウィンドウは常に親ウィンドウに含まれ，必要ならクリップされます．親ウィンドウの中に複数の小ウィンドウを持つことができます．

クライアント・エリア

　ウィンドウ内の使用可能な領域をクライアント・エリアと呼びます．フレームやタイトル・バーを持つウィンドウの場合，クライアント・エリアはその内側の四角い領域になります．フレームを持たないウィンドウであれば，ウィンドウの座標はクライアント・エリアと同じです．

クリップ・エリア

　ウィンドウやその一部の領域を制限する処理をクリッピングと呼びます．クリップされた領域とは，ウィンドウの可視な領域です．Z位置が高い他の子ウィンドウがあれば，そのウィンドウにクリップされます．自ウィンドウが親ウィンドウからはみ出す領域もクリップされます．

座標

　ピクセルを単位とした2軸の座標系です．2つの数値で表現し，最初の数値が水平方向（X軸），2つめが垂直方向（Y軸）です．

カレント・ウィンドウ

　アクティブ・ウィンドウと同義です．

デスクトップ座標

　ディスプレイ座標です．ディスプレイの左上が原点（0，0）です．

デスクトップ・ウィンドウ

　ウィンドウ・マネージャによって自動的に生成されます．常にディスプレイ領域全体をカバーします．全てのレイヤーはデスクトップ・ウィンドウを持ちます．デスクトップは常に最下層のウィンドウであり，他のウィンドウが定義されていなければデフォルト・ウィンドウとなります．全てのウィンドウは，現在選択されているレイヤーで，デスクトップ・ウィンドウの階層に含まれます（子や孫になる）．デスクトップ・ウィンドウはバッファを持ちます．それはvoid型のデータ用です．これによってユーザはデータを追加できます（構造体へのポインタなどの）．

早期クリップ

　デフォルトのクリッピング・モードです．ウィンドウがペイント・イベントを受け取る前にクリッピングが処理されます．カレント・ウィンドウがクリップ処理されなければならない時，1回の描画処理で1つ以上のWM_PAINTメッセージを受け取ります．
　低速クリッピング・モードでは，ウィンドウは常に1つだけWM_PAINTメッセージを受け取ります．このモードではクリッピングは描画時に行われます．

ウィジェット

　ウィジェットはオブジェクト・プロパティーを持ったウィンドウです．ユーザー・インターフェースを構成し，ウィンドウ・システムでコントロールと呼ばれます．特定のイベントに自動的に反応します．例えばボタンはクリックされた時，見た目でクリックされたことが分かります．ウィジェットは存在している間有効なプロパティーを持ちます．使われなくなった時，消すこともできます．ウィジェットはウィンドウと同じく，イベント処理ルーチンから参照されます．
　ウィジェットはウィンドウ・マネージャーを必要とします．ウィジェットは作られたあと，他のウィンドウと同じように扱われます．ウィンドウ・マネージャーはウィジェットが必要な時描画（そして再描画）されるよう保証します．アプリケーションにとってウィジェットを使うことは必須ではありませんが，使えばそれは開発期間の短縮に寄与します．ウィジェットは本質的にウィンドウなので，ほとんどのウィンドウ・マネージャーAPIを利用可能です．

概要

用意されているウィジェット

　次の表に現在利用可能なウィジェットの外観を示します．幾つかのウィジェットはスキニングをサポートします．見た目を変更するこの方法の詳細は，スキニングの章で扱います．2番目のスクリーン・ショットはスキニングを有効にした時の外観です．

ウィジェット	特徴
ボタン	テキストやビットマップを表示できる
チェックボックス	オンかオフの状態を取る
ドロップダウン（コンボボックス）	クリックすると開くリストボックス
エディット（テキストフィールド）	1行のテキスト領域
フレーム（ダイアログ）	フレーム付きのウィンドウ
ゲージ	円形のプログレスバー
グラフ	グラフ
ヘッダー	桁を管理する
アイコン	モバイル機で良く使われるアイコン
イメージ	幾つかの画像フォーマットに対応する
キーボード	スクリーンキーボード
ノブ（obsolete）	アンカウンタブルな値の入力向き
リストボックス	選択されたアイテムが反転表示される
リストビュー	表を管理する
リストホイール	スワイプで値を選択しやすいリストホイール
メニュー	水平/垂直メニュに対応
マルチエディット（テキストエリア）	複数行テキスト入力
マルチページ（タブ）	複数ページを持つダイアログ用
プログレスバー	進捗を表示する
QRコード	QRコード
ラジオボタン	複数の選択候補から1つだけを選択できる
ロータリー	アンカウンタブルな値向き（1周できる）
スクロールバー	水平/垂直用がある
スライダー	値を変更するスライダー
スピンボックス	値を調整しやすい数値入力
スワイプリスト	タッチ画面でスワイプ操作できるリスト
スイッチ	トグルできるスイッチ
テキスト（ラベル）	ダイアログで使われる静的なテキスト
ツリービュー	階層構造を管理する

カスタム・ウィジェット・タイプ

　カスタム・ウィジェットを作れます．既存のウィジェットの特定機能を守るためカスタム・コールバック関数を使う必要があります．カスタム・ウィジェットを作る場合，シンプルなウィンドウを使って実装することをお勧めします．DocフォルダにあるAN03002_Custom_Widget_Type.pdfを参考にできます．

再描画メカニズムの理解

　ウィジェットはそのプロパティに応じて自らを描画します．この処理はWM_Exec(), GUI_Exec()が呼ばれた時，あるいはGUI_Delay()が呼ばれた時に行われます．マルチタスクのシステムでは通常WM_Exec()を使ってウィジェットのアップデートを行います（コールバック関数で，他のウィンドウも処理される）．
ウィジェットのプロパティが変更された際，ウィジェットのウィンドウ（もしくはその一部）は無効の印がつけられます．しかしすぐには再描画されません．したがって，その部分の処理は素早く終わります．
　再描画処理はウィンドウ・マネージャによって後程行われるか，WM_Paint()を呼ぶことで強制的に行われます（もしくは全てのウィンドウが再描画されている時にWM_Exec()が呼ばれる）．

ウィジェットの使い方

　次のコードだけでプログレスバーを表示できます．

PROGBAR_Handle hProgBar;
GUI_DispStringAt("Progress bar", 100, 20);
hProgBar = PROGBAR_Create(100, 40, 100, 20, WM_CF_SHOW);

　最初の行は，ウィジェット用の変数宣言です．
　最後の行で，ウィジェットの実体が作られます．
　ウィンドウ・マネージャによって，次回WM_Exec()が呼ばれた時，ウィジェットは自動的に描画されます．これは別タスクとして行われるでしょう．
　外観を変更するための関数がそれぞれのウィジェットに用意されています．これらの関数は1つ目の引数としてウィジェットを取ります．
　45％表示のプログレスバーを作り，色をデフォルト（ダークグレー/ライトグレー）から緑/赤に変えるには，次のコードを実行します．

PROGBAR_SetBarColor(hProgBar, 0, GUI_GREEN);
PROGBAR_SetBarColor(hProgBar, 1, GUI_RED);
PROGBAR_SetValue(hProgBar, 45);

Default configuration

　全てのウィジェットは，フォントや色のデフォルト設定を定義するため，1つもしくは複数のコンフィグレーション・マクロを持っています．それぞれのウィジェットについて有効なコンフィグレーション方法をそれぞれのセクションで後述しています．
　ウィジェットは，最初デフォルトのコンフィグレーションに設定されますが，プロパティについては考慮されません．

How widgets communicate

　ウィジェットは子ウィンドウとして生成されます．親ウィンドウはどのようなタイプのウィンドウでも良く，ほかのウィジェットの場合もあります．協調動作するため，親ウィンドウは子ウィンドウで何か起こった場合，通知を受ける必要があります．子ウィンドウ（ウィジェット）はイベント発生時にWM_NOTIFY_PARENTメッセージを使って親ウインドウと通信します．イベントによってメッセージは異なります．
　ほとんどのウィジェットは，イベントを伝えるために，1つもしくは，複数のノーティフィケーション・コードを持ちます．
　それぞれのウィジェットが持つ，ノーティフィケーション・コードはそれぞれのセクションに列挙されています．

Skinning

　ウィジェットの外観は，ウィジェットのメンバ関数で変更できます．
　幾つかのウィジェットはスキニングをサポートします．ウィジェットにスキニングが使われると，スキンがウィジェットの外観を決定し，メンバ関数は効果を失います．詳細はスキニングの章を参照してください．

Dynamic memory usage for widgets

In embedded applications it is usually not very desirable to use dynamic memory at all because of fragmentation effects. 断片化
これを防ぐための戦略は色々ありますが，それらはいづれもアプリケーション内でメモリ領域をポインタで参照することで限られた状況で効果を発揮します．
　このため，emWinでは異なるアプローチをとります．
全てのオブジェクト（そしてランタイムデータ）は，メモリ領域でハンドルによって参照されます．そのため実行時にアロケートメモリ領域内で再配置が可能になります．したがってポインタを使う場合に起こるロング・ターム・アロケーションを防ぐことができます．全てのウィジェットはハンドルによって参照されます．

Determine the type of a widget

The type of a widget can be determined by comparing the callback function of a specific widget with the public callback functions of the widget API.
次の短い例では，どのようにウィジェットのタイプが決定されるかを示します．コールバック関数がオーバーライドされている場合，メソッドは適合されなければなりません．

WM_CALLBACK * pCb;
pCb = WM_GetCallback(hWidget);
if (pCb == BUTTON_Callback) {
 // Widget is a button
} else if (pCb == DROPDOWN_Callback) {
 // Widget is a dropdown
} else if (pCb == LISTBOX_Callback) {
 // Widget is a listbox
} else if (...) {
 ...
}

　このコードは，コールバック関数がオーバーライドされていない場合に有効です．
カスタム・コールバック関数が使われる場合，上記コードは調整が必要です．

コンフィグレーション・オプション

ウィジェットAPI

6.2.4

ウィンドウ・マネージャでのウィジェットの処理

　ウィジェットは本質的にはウィンドウなので，どのウィンドウ・マネージャの処理とも互換性があります．
　ウィジェットのハンドルはhWinパラメータとして扱われ，他のウィンドウと同じように扱われます．
　ウィンドウ・マネージャの関数は主として以降のウィジェットとともに使われます．

BUTTON: ボタン・ウィジェット

　ボタン・ウィジェットはタッチスクリーンでは最も使われる一般的なユーザ・インターフェースです．ボタンにフォーカスがあれば，スペース・キーと，エンター・キーのキー入力に反応することもできます．
　ボタンには，テキストまたはビットマップを表示できます．
GUI_KEY_SPACE
GUI_KEY_ENTER

メモ
全てのボタン関係の処理は，BUTTON*.c，BUTTON.h.にあります．
全ての識別子はBUTTONのプレフィックスが付きます．

Skinning...
このウィジェットではスキニングが有効です．
詳細はスキニングの章を参照ください．

コンフィグレーション・オプション

BUTTON_REACT_ON_LEVEL

　ボタン・ウィジェットのPIDイベントを処理する方法は2つあります．
　ボタン・ウィジェットのPIDイベントを処理するデフォルトの方法は，reacting on level changesだけです．これはボタン・ウィジェットが反応するのは，ボタン上でPID状態が変化する時だけということを意味します．
　これはBUTTON_SetReactOnLevel()関数を呼ぶことで有効にされます．
　obsolete (以前はデフォルトだった)な方法は，ボタン領域の全てのPIDイベントに反応します.
　これにはボタン領域で，ボタンが押されたまま起こるPID moveイベントも含みます．
ボタン・ウィジェットは押されたと認識してしまいます．
　難点は，ボタンが押されたと誤認識する場合がある点です．BUTTON_REACT_ON_LEVELが0もしくは，BUTTON_SetReactOnTouch()関数を呼ぶと，このモードになります．

招かれざる処理は次のように起こります（どのように誤ったクリック処理がなされるか）．

マウスは1度クリックされます
クリックは，拡張状態にあるドロップダウン・ウィジェットの近くで行われます（メニューアイテムを選択しようとして）
そしてドロップダウンの背後のボタンまでもがクリックされたことになってしまいます

BUTTON_BKCOLOR0_DEFAULT, BUTTON_BKCOLOR1_DEFAULT

デフォルトではボタンの押された状態の外観は白色です．
どのようなディスプレイを使っていても，ボタンが押されていることを分かりやすく示すため，意図的に設定されています．
ボタン・ウィジェットのバックグラウンド・カラーを，押した状態と押していない状態で同じにしたい場合，
BUTTON_BKCOLOR1_DEFAULTをBUTTON_BKCOLOR0_DEFAULTと同じにします．

事前に宣言されたID

次のシンボルはIDsを定義します．ボタン・ウィジェットを判別するために使用されます

# define GUI_ID_BUTTON0 0x170
# define GUI_ID_BUTTON1 0x171
# define GUI_ID_BUTTON2 0x172
# define GUI_ID_BUTTON3 0x173
# define GUI_ID_BUTTON4 0x174
# define GUI_ID_BUTTON5 0x175
# define GUI_ID_BUTTON6 0x176
# define GUI_ID_BUTTON7 0x177
# define GUI_ID_BUTTON8 0x178
# define GUI_ID_BUTTON9 0x179

通知コード（Notification codes）

　次のイベントはボタン・ウィジェットから親ウィンドウへWM_NOTIFY_PARENTメッセージとして送られる．

メッセージ	内容
WM_NOTIFICATION_CLICKED	ボタンはクリックされた
WM_NOTIFICATION_RELEASED	ボタンは離された
WM_NOTIFICATION_MOVED_OUT	ボタンがクリックされ，離されることなくポインティング・デバイスがボタンの領域から出た

キーボード入力に対するボタンの反応

　ボタン・ウィジェットは，フォーカスを持っているときキーボード入力に反応できます．

Key	Reaction
GUI_KEY_ENTER	キーが押下され，すぐに離された
GUI_KEY_SPACE	キーが押下され，ボタンの状態は押されているに変わります．キーが離されるとボタンの状態は押されていないに変わります

ボタンAPI

　次の表でボタン関係の処理をアルファベット順にまとめました．

関数

BUTTON_IsPressed()

・機能
　ボタンがクリックされているかどうかを返す．
・シグネチャ
unsigned BUTTON_IsPressed(BUTTON_Handle hObj);

・プロパティ

引数	内容
hObj	ボタン・ウィジェットのハンドリング関数

・返値
1 ボタンが押されている場合
0 ボタンが押されていない場合

BUTTON_SetBitmap()

・機能
　ボタン・ウィジェットにビットマップ画像を描画します．

・シグネチャ
void BUTTON_SetBitmap( BUTTON_Handle hObj, unsigned int Index, const GUI_BITMAP * pBitmap);

・プロパティ

引数	内容
hObj	ボタン・ウィジェットのハンドル
Index	ボタン・ビットマップ・インデックスを参照して下さい．指定できる値の完全なリストがあります
pBitmap	構造体へのポインタ

・返値
　ボタンを押していない状態のビットマップ画像だけが設定された場合，ボタンが押された時や，無効状態でもその画像が表示されます．
　ビットマップ画像の設定を取り消すにはpBitmapにNULLを渡します．

BUTTON_SetBitmapEx()

・機能
ボタン・ウィジェットに使用されるビットマップを設定します．

・シグネチャ
void BUTTON_SetBitmapEx( BUTTON_Handle hObj, unsigned int Index, const GUI_BITMAP * pBitmap, int x, int y);

・プロパティ

引数	内容
hObj	ボタン・ウィジェットのハンドル
Index	ボタン・ビットマップ・インデックスを参照して下さい．指定できる値の完全なリストがあります
pBitmap	bitmap構造体へのポインタ
x	ボタンに関連付けられるビットマップのX座標
y	ボタンに関連付けられるビットマップのY座標

・返値
押されていない状態のビットマップだけ設定した場合，押している状態でも，ボタンが無効な状態でも同じビットマップが使用されます．

BUTTON_SetBkColor()

・機能
ボタン・ウィジェットのバック・グラウンドカラーを設定します．

・シグネチャ
void BUTTON_SetBkColor(BUTTON_Handle hObj, unsigned int Index, GUI_COLOR Color);

・プロパティ

引数	内容
hObj	Handle of BUTTON widget.
Index	ボタンカラー・インデックスのページを参照して下さい．指定できる値の完全なリストがあります
Color	設定するバックグラウンド・カラー

BUTTON_SetBMP()

・機能
ボタン・ウィジェットに表示するビットマップを設定します．

・シグネチャ
void BUTTON_SetBMP( BUTTON_Handle hObj, unsigned int Index, const void * pBitmap);

・プロパティ

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`Index`	ボタン・ビットマップ・インデックスのページを参照して下さい
`pBitmap`	bitmapファイルのポインタ

・追加情報
　ボタンを押していない状態のビットマップ画像だけが設定された場合，ボタンが押された時や，無効状態でもその画像が表示されます．
　ビットマップ・ファイルについての詳細はBMPファイルサポートのページを参照してください．

BUTTON_SetBMPEx()

・機能
　表示位置を指定して，ボタン・ウィジェットにビットマップ画像を設定します．

・シグネチャ
void BUTTON_SetBMPEx( BUTTON_Handle hObj, unsigned int Index, const void * pBitmap, int x, int y);

・プロパティ

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`Index`	ボタンのビットマップ・インデックスを参照して下さい．値の完全なリストがあります．
`pBitmap`	BMPファイルのポインタ
`x`	ボタンに関連付けるビットマップ・ファイルのX座標
`y`	ボタンに関連付けるビットマップ・ファイルのY座標

BUTTON_SetDefaultBkColor()

Description
　ボタン・ウィジェットにデフォルトのバックグラウンド・カラーを設定します．

シグネチャ
void BUTTON_SetDefaultBkColor(GUI_COLOR Color, unsigned Index);

引数

引数	内容
`Color`	使用する色
`Index`	ボタン・カラー・インデックスのページを参照して下さい．値の完全なリストがあります．

BUTTON_SetDefaultFocusColor()

Note
This function is deprecated and only works in conjunction with the classic skin (BUT-TON_SetSkinClassic()). Skinning props should be used instead which can be set via BUTTON_SetSkinFlexProps().

Description
　ボタン・ウィジェットにフォーカスされた時のデフォルトの矩形カラーを設定します．

シグネチャ
GUI_COLOR BUTTON_SetDefaultFocusColor(GUI_COLOR Color);

引数

引数	内容
`Color`	ボタン・ウィジェットに使用されるデフォルト・カラー

返り値
　以前のデフォルトのrectangle color値．

　詳細はBUTTON_SetFocusColor()を参照してください．

BUTTON_SetDefaultFont()

Description
　ボタン・ウィジェットのテキスト用のデフォルト・フォントをポインタで渡します．

シグネチャ
void BUTTON_SetDefaultFont(const GUI_FONT * pFont);

引数

引数	内容
`pFont`	GUI_FONT構造体へのポインタ

BUTTON_SetDefaultTextAlign()

Description
　ボタン・ウィジェットのテキストのデフォルトの揃え方を指定します．

シグネチャ
void BUTTON_SetDefaultTextAlign(int Align);

引数

引数	内容
`Align`	Text alignmentモード. 指定可能なフラグについては，テキスト・アライメント・フラグ（Text alignment flags）のページを参照してください．

BUTTON_SetDefaultTextColor()

Description
　ボタン・ウィジェットのテキストのデフォルトの色を指定します．

シグネチャ
void BUTTON_SetDefaultTextColor(GUI_COLOR Color, unsigned Index);

引数

引数	内容
`Color`	デフォルトのテキスト色
`Index`	ボタン・カラー・インデックスのページを参照して下さい．有効な値のリストがあります

BUTTON_SetFocusColor()

Note
　この機能はdeprecated（古い）です．そしてクラシック・スキンと共に複雑に動作します（BUTTON_SetSkinClassic().
　BUTTON_SetSkinFlexProps()を使う代わりにスキニングが使われます．

Before After

Description
ボタン・ウィジェットのフォーカスを示す矩形の描画色を設定します．

シグネチャ
GUI_COLOR BUTTON_SetFocusColor(BUTTON_Handle hObj, GUI_COLOR Color);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`Color`	フォーカスを示す矩形の色

返値は，以前のフォーカス用矩形描画色です．
追加情報
フォーカスの矩形は，ウィジェットが入力フォーカスを取得した時のみ描画されます．

BUTTON_SetFocusable()

Description
入力フォーカスが設定できるかどうかを設定します

シグネチャ
void BUTTON_SetFocusable(BUTTON_Handle hObj, int State);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`State`	以下の表を参照して下さい

引数として取れる値

---|---
1 | ボタンは入力フォーカスを持てる
0 | ボタンは入力フォーカスを持てない

BUTTON_SetFont()

Description
　ボタン・ウィジェットにフォントを設定します．

シグネチャ
void BUTTON_SetFont(BUTTON_Handle hObj, const GUI_FONT* pfont);

引数

引数	内容
`hObj`	Handle of BUTTON widget.
`pFont`	フォントのポインタ

追加情報
　フォントが選択されていない場合，BUTTON_FONT_DEFが使われます．

BUTTON_SetFrameColor()

Note
　この機能はdeprecatedです．
This function is deprecated and only works in conjunction with the classic skin (BUTTON_SetSkinClassic()). Skinning props should be used instead which can be set via BUTTON_SetSkinFlexProps().

Description
　ボタン・ウィジェットのフレーム色を設定します．

シグネチャ
void BUTTON_SetFrameColor(BUTTON_Handle hObj, GUI_COLOR Color);

Parameters

Parameter	Description
`hObj`	Handle of BUTTON widget.
`Color`	Color of the frame.

BUTTON_SetPressed()

Description
ボタンが，押されている状態かどうかを設定します．

シグネチャ
void BUTTON_SetPressed(BUTTON_Handle hObj, int State);

引数

Parameter	Description
`hObj`	Handle of BUTTON widget.
`State`	1の場合はボタンは押されている状態となります．0の場合はボタンは押されていない状態となります

BUTTON_SetReactOnLevel()

Description
Sets all BUTTON widgets to react on level changes of the PID.

Prototype
void BUTTON_SetReactOnLevel(void);

追加情報
この関数を使う代わりに，コンフィグレーションのBUTTON_REACT_ON_LEVELを使用することもできます．

BUTTON_SetReactOnTouch()

Description
全てのボタン・ウィジェットはタッチイベントに反応するようになります．

シグネチャ
void BUTTON_SetReactOnTouch(void);

追加情報
ボタン・ウィジェットのデフォルトの設定では，タッチイベントに反応します．

BUTTON_SetStreamedBitmap()

Description
ボタン・ウィジェットが表示されるとき，ストリームbitmapを使うように設定します．

シグネチャ
void BUTTON_SetStreamedBitmap(BUTTON_Handle hObj, unsigned int Index, const GUI_BITMAP_STREAM * pBitmap);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`Index`	ボタンbitmapインデックスのページを参照して下さい．指定できる値の完全なリストがあります
`pBitmap`	bitmapストリームのポインタ

追加情報
ストリームbitmap（streamed bitmaps）についての詳細は，ストリームbitmapの描画を参照して下さい．

例
BUTTON_SetStreamedBitmap(hButton, BUTTON_CI_UNPRESSED, (const GUI_BITMAP_STREAM*)acImage);

BUTTON_SetStreamedBitmapEx()

Description
ボタン・ウィジェットが表示されるとき，ストリームbitmapを使うように設定します．

シグネチャ
void BUTTON_SetStreamedBitmapEx(BUTTON_Handle hObj, unsigned int Index, const GUI_BITMAP_STREAM * pBitmap, int x, int y);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`Index`	ボタン・ビットマップ・インデックスのページを参照して下さい．指定可能な値の完全なリストがあります
`pBitmap`	ビットマップ・ストリームのポインタ
`x`	ボタンに関連付けられたビットマップのX座標
`y`	ボタンに関連付けられたビットマップのY座標

追加情報
ストリームbitmap（streamed bitmaps）についての詳細は，ストリームbitmapの描画を参照して下さい．

BUTTON_SetText()

Description
ボタン・ウィジェットに表示されるテキストを設定します．

シグネチャ
int BUTTON_SetText(BUTTON_Handle hObj, const char* s);

引数

引数	内容
`hObj`	Handle of BUTTON widget.
`s`	表示するテキスト

返値
0 成功
1 失敗

BUTTON_SetTextAlign()

Description
ボタン・ウィジェットのテキストの整列方法を設定します．

シグネチャ
void BUTTON_SetTextAlign(BUTTON_Handle hObj, int align);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`Align`	テキスト・アライメント・モード．設定可能な値のリストは，テキスト・アライメント・フラグのページにあります（Text alignment flags）．

追加情報
デフォルトのテキスト・アライメントの値はGUI_TA_HCENTER | GUI_TA_VCENTERです．

BUTTON_SetTextColor()

Description
ボタン・ウィジェットに表示するテキストの色を設定します．

シグネチャ
void BUTTON_SetTextColor(BUTTON_Handle hObj, unsigned int Index, GUI_COLOR Color);

引数

引数	内容
`hObj`	Handle of BUTTON widget.
`Index`	See Button color indexes on page for a full list of permitted values.
`Color`	設定するテキスト色

BUTTON_SetTextOffset()

Description
現在のテキスト・アライメントの設定を考慮してボタン・テキストの位置を調整します．

シグネチャ
void BUTTON_SetTextOffset(BUTTON_Handle hObj, int xPos, int yPos);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`xPos`	X軸のオフセット．デフォルトは0
`yPos`	Y軸のオフセット．デフォルトは0

BUTTON_SetToggleMode()

Description
ボタン・ウィジェットのトグル・モードを有効にします．このモードが有効になると，ボタン・ウィジェットはクリックされるたびに，押された状態と離された状態が切り替わります．

シグネチャ
void BUTTON_SetToggleMode(BUTTON_Handle hObj, int OnOff);

引数

引数	内容
`hObj`	ボタン・ウィジェットのハンドル
`OnOff`	トグルモードが有効な時は1．無効な時は0

BUTTON_SetUserData()

Description
シグネチャはこの章の初めで_SetUserData()として説明されています．

BUTTON_Toggle()

Description
指定したボタンの押下状態をトグルします

シグネチャ
int BUTTON_Toggle(BUTTON_Handle hObj);

引数

引数	内容
hObj	ボタン・ウィジェットのハンドル

返値
-1 異常が発生した時
0 押されていない状態に設定された時
1 押された状態に設定された時

Defines

BUTTON bitmap indexes

Description
ボタン・ウィジェット用のBitmapインデックス
Definition
#define BUTTON_BI_UNPRESSED 0
#define BUTTON_BI_PRESSED 1
#define BUTTON_BI_DISABLED 2

Symbols

定義	内容
BUTTON_BI_UNPRESSED	押していない状態
BUTTON_BI_PRESSED	押している状態
BUTTON_BI_DISABLED	押していない状態

BUTTON color indexes

Description
ボタン・ウィジェットのカラー・インデックス

Definition
#define BUTTON_CI_UNPRESSED 0
#define BUTTON_CI_PRESSED 1
#define BUTTON_CI_DISABLED 2
Symbols

Definition	Description
BUTTON_CI_UNPRESSED	無効状態の色
BUTTON_CI_PRESSED	押された状態の時の色
BUTTON_CI_DISABLED	押されていない状態の時の色

例

Sampleフォルダには，ウィジェットをどのように使用するかを示す以下のサンプルが含まれています．
• WIDGET_ButtonSimple.c
• WIDGET_ButtonPhone.c
• WIDGET_ButtonRound.c
幾つかの他のサンプルも，このウィジェットの使い方を知る助けになります.
Screenshot of WIDGET_ButtonSimple.c:
Screenshot of WIDGET_ButtonPhone.c:
Screenshot of WIDGET_ButtonRound.c:

CHECKBOX: チェックボックス・ウィジェット

幾つかの候補から選択する最もよく使われるウィジェットがチェックボックスです．チェックボックスはユーザにチェックされたり，チェックを外されたりします．複数のチェックボックスを同時に選択可能です．チェックボックスが入力フォーカスを持っている状態であれば，キーボードのスペースキーでチェックボックスを操作できます．
無効な状態の時は，グレーで表示されます．次の表にチェックボックスの外観を示します．

Note
全てのチェックボックスはCHECKBOX*.c，CHECKBOX.hファイルの処理に関連付けられます．
全ての識別子は頭にCHECKBOXが付きます．

…is available for this widget. The screenshot above shows the widget using the default skin.
詳細はスキニングの章を参照して下さい．

コンフィグレーション・オプション

Type | Macro | Default | Description
---|---
N | CHECKBOX_BKCOLOR_DEFAULT | 0xC0C0C0 | デフォルトの背景色
N | CHECKBOX_BKCOLOR0_DEFAULT | 0x808080 | デフォルト・イメージの背景色．無効状態
N | CHECKBOX_BKCOLOR1_DEFAULT | GUI_WHITE | デフォルト・イメージの背景色．有効状態
N | CHECKBOX_FGCOLOR0_DEFAULT | 0x101010 | デフォルト・イメージの前景色．無効状態
N | CHECKBOX_FGCOLOR1_DEFAULT | GUI_BLACK | デフォルト・イメージの前景色．有効状態
N | CHECKBOX_FOCUSCOLOR_DEFAULT | GUI_BLACK | フォーカスを示す矩形の描画色
S | CHECKBOX_FONT_DEFAULT | &GUI_Font13_1 | オプショナルのチェックボックス・テキストのデフォルト・フォント
S | CHECKBOX_IMAGE0_DEFAULT (see table above) | | チェック時に描画されるビットマップのポインタ．無効状態
S | CHECKBOX_IMAGE1_DEFAULT (see table above) | | チェック時に描画されるビットマップのポインタ．有効状態
N | CHECKBOX_SPACING_DEFAULT | 4 | ボックスの横に描画されるオプショナルのチェックボックス・テキストで使われるスペース
N | CHECKBOX_TEXTALIGN_DEFAULT GUI_TA_LEFT | GUI_TA_VCENTER | オプショナルのチェックボックス・テキストのデフォルトの整列状態
N | CHECKBOX_TEXTCOLOR_DEFAULT | GUI_BLACK | オプショナルのチェックボックス・テキストのデフォルトの色

事前に定義された IDs

次の識別子は，チェックボックス・ウィジェットを識別するためにIDsとして定義されています．
#define GUI_ID_CHECK0 0x120
#define GUI_ID_CHECK1 0x121
#define GUI_ID_CHECK2 0x122
#define GUI_ID_CHECK3 0x123
#define GUI_ID_CHECK4 0x124
#define GUI_ID_CHECK5 0x125
#define GUI_ID_CHECK6 0x126
#define GUI_ID_CHECK7 0x127
#define GUI_ID_CHECK8 0x128
#define GUI_ID_CHECK9 0x129

Notification codes

次のイベントがチェックボックス・ウィジェットからWM_NOTIFY_PARENTメッセージとして親ウィンドウに送信されます．

キーボード・リアクション

このウィジェットは，入力フォーカスを持っているとき，次のキーに反応します．
メッセージ | 内容
GUI_KEY_SPACE | チェックボックス・ウィジェットのチェック状態をトグルする

チェックボックスAPI

The table below lists the available emWin CHECKBOX-related routines in alphabetical order.
Detailed descriptions of the routines follow.

Functions

Routine	Description
CHECKBOX_Check()	Set the state of CHECKBOX to checked. (Obsolete)
CHECKBOX_Create()	Creates a CHECKBOX widget. (Obsolete)
CHECKBOX_CreateEx()	チェックボックス・ウィジェットを作る
CHECKBOX_CreateIndirect()	リソース・テーブルエントリからチェックボックス・ウィジェットを作る
CHECKBOX_CreateUser()	ユーザデータとしてエキストラバイトを使ってチェックボックス・ウィジェットを作る
CHECKBOX_GetBkColor()	チェックボックスの現在の背景色を返す
CHECKBOX_GetBoxBkColor()	チェックボックスのボックスの色を返す
CHECKBOX_GetDefaultAlign()	チェックボックス・ウィジェットに使われるデフォルトのテキスト整列モードを返す
CHECKBOX_GetDefaultBkColor()	チェックボックスのデフォルトの背景色を返す
CHECKBOX_GetDefaultFont()	チェックボックス・ウィジェットにテキストを表示するためのGUI_FONT構造体のポインタを返す
CHECKBOX_GetDefaultSpacing()	チェックボックス・ウィジェットのテキストとボックス間の距離のデフォルト値を返す
CHECKBOX_GetDefaultTextAlign()	チェックボックス・ウィジェットのデフォルトのテキスト整列モードを返す
CHECKBOX_GetDefaultTextColor()	チェックボックス・ウィジェットのデフォルトのテキスト色を返す
CHECKBOX_GetFocusColor()	現在のフォーカス・カラーを返す
CHECKBOX_GetFont()	現在設定されているフォントを返す
CHECKBOX_GetImage()	与えられたインデックスに設定されている画像を返す
CHECKBOX_GetState()	指定したチェックボックスの現在の状態を返す
CHECKBOX_GetText()	指定したチェックボックス・ウィジェットのオプションのテキストを返す
CHECKBOX_GetTextAlign()	指定したテキスト・ウィジェットの整列モードを返す
CHECKBOX_GetTextColor()	現在のテキスト色を返す
CHECKBOX_GetUserData()	Retrieves the data set with CHECKBOX_SetUserData().
CHECKBOX_IsChecked()	指定したチェックボックスの現在の状態 (チェック済みorチェックしていない) を返す
CHECKBOX_SetBkColor()	チェックボックス・ウィジェットの背景色を設定する
Routine	Description
---	---
CHECKBOX_SetBoxBkColor()	Sets the background color of the box area.(Obsolete)
CHECKBOX_SetDefaultAlign()	チェックボックス・ウィジェットのデフォルトのテキスト整列モードを設定する
CHECKBOX_SetDefaultBkColor()	チェックボックス・ウィジェットのデフォルトの背景色を設定する
CHECKBOX_SetDefaultFocusColor()	チェックボックス・ウィジェットのフォーカス矩形の描画色を設定する
CHECKBOX_SetDefaultFont()	チェックボックス・ウィジェットのテキストの表示に使われるGUI_FONT構造体のポインタを設定する
CHECKBOX_SetDefaultImage()	チェックされた時に表示されるデフォルトの画像を設定する
CHECKBOX_SetDefaultSpacing()	ボックスとテキストの間のデフォルトの距離を設定する
CHECKBOX_SetDefaultTextAlign()	チェックボックス・ウィジェットのデフォルトのテキスト整列モードを設定する
CHECKBOX_SetDefaultTextColor()	チェックボックス・ウィジェットのデフォルトのテキスト色を設定する
CHECKBOX_SetFocusColor()	フォーカス矩形の色を設定する
CHECKBOX_SetFont()	チェックボックスのフォントを設定する
CHECKBOX_SetImage()	チェックボックス・ウィジェットがチェックされた時に表示される画像を設定する
CHECKBOX_SetNumStates()	チェックボックス・ウィジェット取りうる状態数を設定する(2 or 3).
CHECKBOX_SetSpacing()	ボックスとテキストの距離を設定する
CHECKBOX_SetState()	状態を設定する
CHECKBOX_SetText()	テキストを設定する
CHECKBOX_SetTextAlign()	テキスト整列モードを設定する
CHECKBOX_SetTextColor()	テキスト色を設定する
CHECKBOX_SetUserData()	エキストラデータを設定する
CHECKBOX_Uncheck()	チェックされていない状態に設定する (Obsolete)

Defines
Group of defines Description
CHECKBOX bitmap indexes Bitmap indexes for CHECKBOX widget.
CHECKBOX color indexes Color indexes for CHECKBOX widget.

関数

CHECKBOX_Check()

Note
この関数はdeprecatedです
代わりにCHECKBOX_SetState()を使用して下さい．

Description
Sets the state of a specified CHECKBOX widget to checked.

Prototype
void CHECKBOX_Check(CHECKBOX_Handle hObj);

引数

引数	内容
hObj	Handle of CHECKBOX widget.

CHECKBOX_Create()

Note
この関数はdeprecatedです．
代わりにCHECKBOX_CreateEx()を使用して下さい．

Description
Creates a CHECKBOX widget of a specified size at a specified location.

Prototype
CHECKBOX_Handle CHECKBOX_Create(int x0, int y0, int xSize, int ySize, WM_HWIN hParent, int Id, int Flags);

Parameters

Parameter	Description
x0	チェックボックスの左端位置（親ウィンドウの座標)．
y0	Topmost pixel of the check box (in parent coordinates).
xSize	チェックボックスの水平方向のサイズ(ピクセル)．
ySize	Vertical size of the check box (in pixels).
hParent	親ウィンドウのハンドル
Id	返されるID

Flags
ウィンドウはflagsを生成します．典型的にはWM_CF_SHOWです．ただちにウィジェットを見えるようにします
(ウィンドウのフラグ生成を参照してください．有効な値の一覧があります).

返値
生成されたチェックボックス・ウィジェットのハンドル．関数が失敗した時は0が返されます．

追加情報
xSizeもしくはySizeが0の場合，ビットマップのサイズはチェックボックスのデフォルト・サイズになります

CHECKBOX_CreateEx()

Description
チェックボックス・ウィジェットを指定したサイズで指定した場所に作成します．

シグネチャ
CHECKBOX_Handle CHECKBOX_CreateEx(int x0, int y0, int xSize, int ySize, WM_HWIN hParent, int WinFlags, int ExFlags, int Id);

引数

引数	内容
x0	左端の座標(in parent coordinates).
y0	上端の座標(in parent coordinates).
xSize	チェックボックスの横のサイズ(in pixels).
ySize	チェックボックスの縦のサイズ(in pixels).
hParent	親ウィンドウのハンドル
WinFlags	ウィンドウはflagsを生成します．典型的にはWM_CF_SHOWです．ただちにウィジェットを見えるようにします
(ウィンドウのフラグ生成を参照してください．有効な値の一覧があります).
ExFlags	使用しない．将来のための予約
Id	IDが返される

返値
生成されたチェックボックス・ウィジェットのハンドル．関数が失敗した場合0が返されます．

追加情報
xSizeもしくはySizeが0の場合，デフォルトのチェックボックスのビットマップ・サイズ（11×11）にエフェクトサイズを足したサイズがデフォルト・サイズとして使用されます．
デフォルトと異なるサイズが必要であれば，CHECKBOX_SetImage()を使ってユーザ定義のチェックボックスのビットマップを設定して下さい．テキストボックスのテキストが重要であれば，ボックス＋テキスト＋間のスペースを考慮してチェックボックスを十分大きくして下さい．

CHECKBOX_CreateIndirect()

Description
この関数のシグネチャは，この章の始めで解説されています．
詳細は_CreateIndirect()関数のページを参照して下さい．
The elements Flags and Para of the according GUI_WIDGET_CREATE_INFO structure are not used.

CHECKBOX_CreateUser()

Description
この章の始めで_CreateUser()のシグネチャが解説されています．引数についての詳細はCHECKBOX_CreateEx()を参照して下さい

CHECKBOX_GetBkColor()

Description
現在の背景色を返す

シグネチャ
GUI_COLOR CHECKBOX_GetBkColor(CHECKBOX_Handle hObj);

引数

引数	内容
hObj	チェックボックス・ウィジェットのハンドル
返値
The color currently used as background color.

CHECKBOX_GetBoxBkColor()

Description
現在の背景色を返す

Prototype
GUI_COLOR CHECKBOX_GetBoxBkColor(CHECKBOX_Handle hObj, int Index);

引数

引数	内容
hObj	チェックボックス・ウィジェットのハンドル
Index	See Checkbox color indexes on page for a full list of permitted values.

Return value
Background color used for the corresponding state.

CHECKBOX_GetDefaultAlign()

Description
Returns the default text alignment used for CHECKBOX widgets.

Prototype
int CHECKBOX_GetDefaultAlign(void);

返値
Default text alignment. Refer to Text alignment flags on page 238 a list of permitted values.

CHECKBOX_GetDefaultBkColor()

Description
Returns the default background color of new CHECKBOX widgets.

Prototype
GUI_COLOR CHECKBOX_GetDefaultBkColor(void);

Return value
Default background color of new CHECKBOX widgets.

Additional information
The background color returned by this function is not the background color shown in the box, but the background color of the rest of the widget.
For more information, refer to CHECKBOX_SetBoxBkColor().

CHECKBOX_GetDefaultFont()

Description
Returns a pointer to a GUI_FONT structure used to display the text of new CHECKBOX widgets.

Prototype
GUI_FONT *CHECKBOX_GetDefaultFont(void);

Return value
Pointer to a GUI_FONT structure used to display the text of new CHECKBOX widgets.

Additional information
For more information, refer to CHECKBOX_SetFont().

CHECKBOX_GetDefaultSpacing()

Description
Returns the default spacing between box and text used to display the text of new CHECKBOX widgets.

Prototype
int CHECKBOX_GetDefaultSpacing(void);

返値
Default spacing between box and text used to display the text of new CHECKBOX widgets.

追加情報
For more information, refer to CHECKBOX_SetSpacing().

CHECKBOX_GetDefaultTextAlign()

Description
Returns the default alignment used to display the text of new CHECKBOX widgets.

Prototype
int CHECKBOX_GetDefaultAlign(void);

返値
Default alignment used to display the text of new CHECKBOX widgets.

追加情報
For more information, refer to CHECKBOX_SetTextAlign() on page 1037.

CHECKBOX_GetDefaultTextColor()

Description
Returns the default text color used to display the text of new CHECKBOX widgets.

Prototype
GUI_COLOR CHECKBOX_GetDefaultTextColor(void);

返値
Default text color used to display the text of new check box widgets.

追加情報
For more information, refer to CHECKBOX_SetTextColor().

CHECKBOX_GetFocusColor()

Description
This function returns the color currently used as focus color.

Prototype
GUI_COLOR CHECKBOX_GetFocusColor(CHECKBOX_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.

返値
The color currently used to draw the focus.

CHECKBOX_GetFont()

Description
Returns the currently set font.

Prototype
GUI_FONT *CHECKBOX_GetFont(CHECKBOX_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.

返値
A pointer the font which is used for the CHECKBOX.

CHECKBOX_GetImage()

Description
Returns the image set for the given index.

Prototype
GUI_BITMAP *CHECKBOX_GetImage(CHECKBOX_Handle hObj, unsigned int Index);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
Index	See Checkbox bitmap indexes on page for a full list of permitted values.

Return value
A pointer the image used with the given index.

CHECKBOX_GetState()

Description
Returns the current state of the given CHECKBOX widget.

Prototype
int CHECKBOX_GetState(CHECKBOX_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.

返値
Current state of the given CHECKBOX widget.

追加情報
Per default a check box can have 2 states, checked (1) and unchecked (0). With the function CHECKBOX_SetNumStates() the number of possible states can be increased to 3. If the check box is in the third state the function returns 2.
For more information, refer to CHECKBOX_SetNumStates().

CHECKBOX_GetText()

Description
Returns the optional text of the given CHECKBOX widget.

Prototype
int CHECKBOX_GetText(CHECKBOX_Handle hObj, char * pBuffer, int MaxLen);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
pBuffer	Pointer to buffer to which the text will be copied.
MaxLen	Buffer size in bytes.

返値
Length of the text copied into the buffer.

追加情報
If the CHECKBOX widget contains no text the function returns 0 and the buffer remains unchanged.

CHECKBOX_GetTextAlign()

Description
This function returns the text alignment of the given TEXT widget.

Prototype
int CHECKBOX_GetTextAlign(CHECKBOX_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.

返値
Returns the currently used text alignment.

CHECKBOX_GetTextColor()

Description
This function returns the color currently used the text.

Prototype
GUI_COLOR CHECKBOX_GetTextColor(CHECKBOX_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.

Return value
The color currently used displaying the text.

CHECKBOX_GetUserData()

Description
Prototype explained at the beginning of the chapter as _GetUserData() on page 935.

CHECKBOX_IsChecked()

Description
Returns the current state (checked or not checked) of a specified CHECKBOX widget.

Prototype
int CHECKBOX_IsChecked(CHECKBOX_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.

Return value
0 not checked
1 checked

CHECKBOX_SetBkColor()

Before After

Description
Sets the background color used to display the background of the CHECKBOX widget.

Prototype
void CHECKBOX_SetBkColor(CHECKBOX_Handle hObj, GUI_COLOR Color);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
Color	Color to be used to draw the background or GUI_INVALID_COLOR to work in transparent mode.

Additional information
If the check box should work in transparent mode GUI_INVALID_COLOR should be used.

CHECKBOX_SetBoxBkColor()

Note
This function is deprecated and only works in conjunction with the classic skin (CHECKBOX_SetSkinClassic()). Skinning props should be used instead which can be set via CHECKBOX_SetSkinFlexProps().

Before After

Description
Sets the background color of the box area.

Prototype
GUI_COLOR CHECKBOX_SetBoxBkColor(CHECKBOX_Handle hObj, GUI_COLOR Color, int Index);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
Color	Color to be used.
Index	See Checkbox color indexes on page for a full list of permitted values.

返値
Previous background color.
Additional information
The color set by this function will only be visible, if the images used by the widget are transparent or no image is used. The default images of this widget are transparent.

CHECKBOX_SetDefaultAlign()

6.2.6.5.1.25
Description
Sets the default text alignment used for new CHECKBOX widgets.

Prototype
void CHECKBOX_SetDefaultAlign(int Align);

Parameters

Parameter	Description
Align	Text alignment flags. See Text alignment flags on page 238 for a full list of permitted values.

CHECKBOX_SetDefaultBkColor()

Description
Sets the default background color used for new CHECKBOX widgets.

Prototype
void CHECKBOX_SetDefaultBkColor(GUI_COLOR Color);

Parameters

Parameter	Description
Color	Color to be used, GUI_INVALID_COLOR for transparency.

Additional information
For more information, refer to CHECKBOX_SetBkColor.

CHECKBOX_SetDefaultFocusColor()

Description
Sets the color used to render the focus rectangle of new CHECKBOX widgets.

Prototype
GUI_COLOR CHECKBOX_SetDefaultFocusColor(GUI_COLOR Color);

Parameters

Parameter	Description
Color	Color to be used.

返値
Previous color used to render the focus rectangle.

Additional information
For mode information, refer to CHECKBOX_SetFocusColor().

CHECKBOX_SetDefaultFont()

Description
Sets a pointer to a GUI_FONT structure used to display the text of new CHECKBOX widgets.

Prototype
void CHECKBOX_SetDefaultFont(const GUI_FONT * pFont);

Parameters

Parameter	Description
pFont	Pointer to GUI_FONT structure to be used.

Additional information
For mode information, refer to CHECKBOX_SetFont().

CHECKBOX_SetDefaultImage()

Description
Sets the images used for new CHECKBOX widgets to be shown if they has been checked.

Prototype
void CHECKBOX_SetDefaultImage(const GUI_BITMAP * pBitmap, unsigned int Index);

Parameters

Parameter | Description
pBitmap | Pointer to bitmap.
Index | See Checkbox bitmap indexes on page for a full list of permitted values.

Additional information
The image has to fill the complete inner area of the CHECKBOX widget.

CHECKBOX_SetDefaultSpacing()

Description
Sets the default spacing between box and text used to display the text of new CHECKBOX
widgets.

Prototype
void CHECKBOX_SetDefaultSpacing(int Spacing);

Parameters

Parameter	Description
Spacing	Number of pixels between box and text used for new CHECKBOX widgets.

Additional information
For more information, refer to CHECKBOX_SetSpacing().

CHECKBOX_SetDefaultTextAlign()

Description
Sets the default alignment used to display the text of new CHECKBOX widgets.

Prototype
void CHECKBOX_SetDefaultTextAlign(int Align);

Parameter	Description
Align	Text alignment mode. List of flags can be found under Text
alignment	flags on page 238.

Additional information
For more information, refer to CHECKBOX_SetTextAlign() on page 1037.

CHECKBOX_SetDefaultTextColor()

Description
Sets the default text color used to display the text of new CHECKBOX widgets.

Prototype
void CHECKBOX_SetDefaultTextColor(GUI_COLOR Color);

Parameters

Parameter	Description
Color	Color to be used.

Additional information
For more information, refer to CHECKBOX_SetTextColor().

CHECKBOX_SetFocusColor()

Before After

Description
Sets the color used to render the focus rectangle.

Prototype
GUI_COLOR CHECKBOX_SetFocusColor(CHECKBOX_Handle hObj, GUI_COLOR Color);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
Color	Color to be used.

Return value
Previous color of the focus rectangle.

Additional information
The focus rectangle is only visible if the widget has the input focus.

CHECKBOX_SetFont()

Description
Sets the font of the CHECKBOX widget.

Prototype
void CHECKBOX_SetFont(CHECKBOX_Handle hObj, const GUI_FONT * pFont);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
pFont	Pointer to the font.

CHECKBOX_SetImage()

Before After

Description
Sets the images to be shown if the CHECKBOX widget has been checked.

Prototype
void CHECKBOX_SetImage(CHECKBOX_Handle hObj, const GUI_BITMAP* pBitmap, unsigned int Index);

Parameters

Parameter Description
hObj | Handle of CHECKBOX widget.
pBitmap | Pointer to bitmap.
Index | See Checkbox bitmap indexes on page for a full list of permitted values.

Additional information
The image has to fill the complete inner area of the check box. If using this function make
sure, the size of the check box used to create the widget is large enough to show the bitmap
and (optional) the text.

CHECKBOX_SetNumStates()

Description
This function sets the number of possible states of the given CHECKBOX widget.

Prototype
void CHECKBOX_SetNumStates(CHECKBOX_Handle hObj, unsigned NumStates);

Parameters

Parameter Description
hObj | Handle of CHECKBOX widget.
NumStates | Number of possible states of the given check box. Currently supported are 2 or 3 states.

Additional information
Per default a check box supports 2 states: checked (1) and unchecked (0). If the check box should support a third state the number of possible states can be increased to 3.

CHECKBOX_SetSpacing()

Before After

Description
Sets the number of pixels between box and text of a given CHECKBOX widget.

Prototype
void CHECKBOX_SetSpacing(CHECKBOX_Handle hObj, unsigned Spacing);

Parameters

Parameter Description
---|---
hObj | Handle of CHECKBOX widget.
Spacing | Number of pixels between box and text to be used.

Additional information
The default spacing is 4 pixels. The function CHECKBOX_SetDefaultSpacing() or the configuration macro CHECKBOX_SPACING_DEFAULT can be used to set the default value.

CHECKBOX_SetState()

6.2.6.5.1.38
Before After

Description
Sets the new state of the given CHECKBOX widget.

Prototype
void CHECKBOX_SetState(CHECKBOX_Handle hObj, unsigned State);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
State	Zero-based number of new state.

Permitted values for parameter State
0 Unchecked
1 Checked
2 Third state

Additional information
The passed state should not be greater than the number of possible states set with CHECKBOX_SetNumStates() minus 1.

CHECKBOX_SetText()

6.2.6.5.1.39
Before After

Description
Sets the optional text shown beside the box.

Prototype
void CHECKBOX_SetText( CHECKBOX_Handle hObj, const char * s);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
s	Pointer to text to be shown beside the box.

Additional information
Clicking on the text beside the box has the same effect as clicking into the box.

CHECKBOX_SetTextAlign()

6.2.6.5.1.40
Before After

Description
Sets the alignment used to display the text beside the box.

Prototype
void CHECKBOX_SetTextAlign(CHECKBOX_Handle hObj, int Align);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
Align	Text alignment mode. List of flags can be found under Text alignment flags on page 238.

Additional information
Per default the text alignment is GUI_TA_LEFT | GUI_TA_VCENTER. The function CHECKBOX_SetDefaultTextAlign() and the configuration macro CHECKBOX_TEXTALIGN_DEFAULT can be used to set a user defined default value.

CHECKBOX_SetTextColor()

6.2.6.5.1.41
Before After

Description
Sets the color used to display the text of the CHECKBOX widget.

Prototype
void CHECKBOX_SetTextColor(CHECKBOX_Handle hObj, GUI_COLOR Color);

Parameters

Parameter	Description
hObj	Handle of CHECKBOX widget.
Color	Desired color of check box text.

Additional information
Per default the text color of a check box text is GUI_BLACK. The function CHECKBOX_SetDefaultTextColor() and the configuration macro CHECKBOX_TEXTCOLOR_DEFAULT can be used to set a user defined default color.

CHECKBOX_SetUserData()

6.2.6.5.1.42
Description
Prototype explained at the beginning of the chapter as _SetUserData() on page 936.

CHECKBOX_Uncheck()

6.2.6.5.1.43
Note
This function is deprecated, CHECKBOX_SetState() should be used instead.

Before After

Description
Sets the state of a specified CHECKBOX widget to unchecked.

Prototype
void CHECKBOX_Uncheck(CHECKBOX_Handle hObj);

Parameter	Description
hObj	Handle of CHECKBOX widget.

Additional information
This is the default setting for CHECKBOX widgets.

Defines

6.2.6.5.2

CHECKBOX bitmap indexes

Description
Bitmap indexes for CHECKBOX widget.

Definition
#define CHECKBOX_BI_INACTIV_UNCHECKED 0
#define CHECKBOX_BI_ACTIV_UNCHECKED 1
#define CHECKBOX_BI_INACTIV_CHECKED 2
#define CHECKBOX_BI_ACTIV_CHECKED 3
#define CHECKBOX_BI_INACTIV_3STATE 4
#define CHECKBOX_BI_ACTIV_3STATE 5

Symbols
Definition Description
CHECKBOX_BI_INACTIV_UNCHECKED

Bitmap displayed when the CHECKBOX is unchecked and disabled.

CHECKBOX_BI_ACTIV_UNCHECKED

Bitmap displayed when the CHECKBOX is unchecked and enabled.

CHECKBOX_BI_INACTIV_CHECKED

Bitmap displayed when the CHECKBOX is checked and disabled.

CHECKBOX_BI_ACTIV_CHECKED

Bitmap displayed when the CHECKBOX is checked and enabled.

CHECKBOX_BI_INACTIV_3STATE

Bitmap displayed when the CHECKBOX is in the third state and disabled.

CHECKBOX_BI_ACTIV_3STATE

Bitmap displayed when the CHECKBOX is in the third state and enabled.

CHECKBOX color indexes

6.2.6.5.2.2
Description
Color indexes for CHECKBOX widget.
Definition

define CHECKBOX_CI_DISABLED 0

define CHECKBOX_CI_ENABLED 1

Symbols
Definition Description
CHECKBOX_CI_DISABLED Color used for disabled state.
CHECKBOX_CI_ENABLED Color used for enabled state.

Example

6.2.6.6
The Sample folder contains the following example which shows how the widget can be used:
• WIDGET_Checkbox.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_Checkbox.c:

DROPDOWN: Dropdown widget

6.2.7
DROPDOWN widgets are used to select one element of a list with several columns. It shows the currently selected item in non open state. If the user opens a DROPDOWN widget a LISTBOX appears to select a new item.
DROPDOWN closed DROPDOWN opened

Note
All DROPDOWN-related routines are located in the file(s) DROPDOWN*.c, DROPDOWN.h.
All identifiers are prefixed DROPDOWN.
If mouse support is enabled, the open list reacts on moving the mouse over it.
Skinning...

…is available for this widget. The screenshot above shows the widget using the default skin.
Details can be found in the chapter Skinning on page 2275.

Configuration options

6.2.7.1

Type | Macro | Default | Description
---|---
N | DROPDOWN_ALIGN_DEFAULT GUI_TA_LEFT Text alignment used to display the dropdown text in closed state.
S | DROPDOWN_FONT_DEFAULT &GUI_Font13_1 Default font.
N | DROPDOWN_BKCOLOR0_DEFAULT GUI_WHITE Background color, unselected state.
N | DROPDOWN_BKCOLOR1_DEFAULT GUI_GRAY Background color, selected state without focus.
N | DROPDOWN_BKCOLOR2_DEFAULT GUI_BLUE Background color, selected state with focus.
N | DROPDOWN_KEY_EXPAND GUI_KEY_SPACE Key which can be used to expand the DROPDOWN list.
N | DROPDOWN_KEY_SELECT GUI_KEY_ENTER Key which can be used to select an item from the open dropdown list.
N | DROPDOWN_TEXTCOLOR0_DEFAULT GUI_BLACK Text color, unselected state.
N | DROPDOWN_TEXTCOLOR1_DEFAULT GUI_BLACK Text color, selected state without focus.
N | DROPDOWN_TEXTCOLOR2_DEFAULT GUI_WHITE Enable 3D support.

Predefined IDs

6.2.7.2
The following symbols define IDs which may be used to make DROPDOWN widgets distinguishable from creation.
#define GUI_ID_DROPDOWN0 0x180
#define GUI_ID_DROPDOWN1 0x181
#define GUI_ID_DROPDOWN2 0x182
#define GUI_ID_DROPDOWN3 0x183
#define GUI_ID_DROPDOWN4 0x184
#define GUI_ID_DROPDOWN5 0x185
#define GUI_ID_DROPDOWN6 0x186
#define GUI_ID_DROPDOWN7 0x187
#define GUI_ID_DROPDOWN8 0x188
#define GUI_ID_DROPDOWN9 0x189

Notification codes

6.2.7.3
The following events are sent from the widget to its parent window as part of a WM_NOTIFY_PARENT message:
Message Description
WM_NOTIFICATION_CLICKED DROPDOWN has been clicked.
WM_NOTIFICATION_RELEASED DROPDOWN has been released.
WM_NOTIFICATION_MOVED_OUT

DROPDOWN has been clicked and pointer has
been moved out of the widget without releasing.

WM_NOTIFICATION_SCROLL_CHANGED

The scroll position of the optional scroll bar of the opened DROPDOWN widget has been changed.
WM_NOTIFICATION_SEL_CHANGED The selection of the DROPDOWN list has been changed.

Keyboard reaction

6.2.7.4
The widget reacts to the following keys if it has the input focus:
Key Reaction
GUI_KEY_ENTER Selects an item from the open DROPDOWN list and closes the list.
GUI_KEY_SPACE Opens the DROPDOWN list.

DROPDOWN API

6.2.7.5
The table below lists the available emWin DROPDOWN-related routines in alphabetical order. Detailed descriptions of the routines follow.

Functions
Routine Description
DROPDOWN_AddString() Adds a new element to the DROPDOWN widget.
DROPDOWN_Collapse() Closes the DROPDOWN list.
DROPDOWN_Create() Creates a DROPDOWN widget. (Obsolete)
DROPDOWN_CreateEx() Creates a DROPDOWN widget.
DROPDOWN_CreateIndirect() Creates a DROPDOWN widget from a resource table entry.
DROPDOWN_CreateUser() bCreates a DROPDOWN widget using extra ytes as user data.
DROPDOWN_DecSel() Decrements selection.
DROPDOWN_DecSelExp() Decrements selection in expanded state.
DROPDOWN_DeleteItem() Deletes the given item of the DROPDOWN widget.
DROPDOWN_Expand() Opens the list of the DROPDOWN widget.
DROPDOWN_GetBkColor() Returns the background color of the given DROPDOWN widget.
DROPDOWN_GetColor() Returns the color used for either the button or the arrow.
DROPDOWN_GetDefaultFont() Returns the default font of DROPDOWN widgets.
DROPDOWN_GetFont() Returns the font currently used by the widget.
DROPDOWN_GetItemDisabled() Returns the state of the given item.
DROPDOWN_GetItemText() Returns the text of a specific item of the given DROPDOWN widget.
DROPDOWN_GetListbox() Returns the handle of the attached LISTBOX widget in expanded state.
DROPDOWN_GetNumItems() Returns the number of items in the given DROPDOWN widget.
DROPDOWN_GetSel() Returns the number of the currently selected item in a specified DROPDOWN widget.
DROPDOWN_GetSelExp() Returns the index of the currently selected item of the attached LISTBOX in expanded state.
DROPDWON_GetTextColor() Returns the color of the text.
DROPDOWN_GetUserData() Retrieves the data set with DROPDOWN_SetUserData().
DROPDOWN_IncSel() Increments selection.
DROPDOWN_IncSelExp() Increments selection in expanded state.
DROPDOWN_InsertString() Inserts a string to the DROPDOWN widget at the given position.

Routine Description
DROPDOWN_SetAutoScroll() Enables the automatic use of a vertical scroll bar in the DROPDOWN widget.
DROPDOWN_SetBkColor() Sets the background color of the given DROPDOWN widget.
DROPDOWN_SetColor() Sets the color of the button or the arrow of the given DROPDOWN widget.
DROPDOWN_SetDefaultColor() Sets the default colors for the arrow and the button of new DROPDOWN widgets.
DROPDOWN_SetDefaultFont() Sets the default font used for new DROPDOWN widgets.
DROPDOWN_SetDefaultScrollbarColor() Sets the default colors used for the optional scroll bar in the DROPDOWN widget.
DROPDOWN_SetFont() Sets the font used to display the given DROPDOWN widget.
DROPDOWN_SetItemDisabled() Sets the enabled state of the given item.
DROPDOWN_SetItemSpacing() Sets an additional spacing below the items of the DROPDOWN widget.
DROPDOWN_SetListHeight() Sets the height in pixels to be used for the expanded list of the DROPDOWN widget.
DROPDOWN_SetScrollbarColor() Sets the colors of the optional scroll bar in the DROPDOWN widget.
DROPDOWN_SetScrollbarWidth() Sets the width of the scroll bars used by the list of the given DROPDOWN widget.
DROPDOWN_SetSel() Sets the current selection.
DROPDOWN_SetSelExp() Sets the selected item of the attached LISTBOX in expanded state.
DROPDOWN_SetTextAlign() Sets the alignment used to display the text of the DROPDOWN widget in closed state.
DROPDOWN_SetTextColor() Sets the text color of the given DROPDOWN widget.
DROPDOWN_SetTextHeight() Sets the height of the rectangle used to display the dropdown text in closed state.
DROPDOWN_SetUpMode() Enables opening of the list to the upper side of the DROPDOWN widget.
DROPDOWN_SetUserData() Sets the extra data of a DROPDOWN widget.

Defines
Group of defines Description
CHECKBOX bitmap indexes Bitmap indexes for CHECKBOX widget.
CHECKBOX color indexes Color indexes for CHECKBOX widget.

Functions

6.2.7.5.1

DROPDOWN_AddString()

6.2.7.5.1.1
Description
Adds a new element to the DROPDOWN widget.

Prototype
void DROPDOWN_AddString(DROPDOWN_Handle hObj, const char * s);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
s	Pointer to string to be added

DROPDOWN_Collapse()

6.2.7.5.1.2
Description
Closes the dropdown list of the DROPDOWN widget.

Prototype
void DROPDOWN_Collapse(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

DROPDOWN_Create()

6.2.7.5.1.3
Note
This function is deprecated, DROPDOWN_CreateEx() should be used instead.

Description
Creates a DROPDOWN widget of a specified size at a specified location.

Prototype
DROPDOWN_Handle DROPDOWN_Create(WM_HWIN hWinParent, int x0, int y0, int xSize, int ySize, int Flags);

Parameters

Parameter	Description
hWinParent	Handle of parent window
x0	Leftmost pixel of the DROPDOWN widget (in parent coordinates).
y0	Topmost pixel of the DROPDOWN widget (in parent coordinates).
xSize	Horizontal size of the DROPDOWN widget (in pixels).
ySize	Vertical size of the DROPDOWN widget in open state (in pixels).

Flags

Window create flags. Typically, WM_CF_SHOW to make the widget visible immediately (refer to Window create flags on page 919 for a list of available parameter values).

Return value
Handle of the created DROPDOWN widget; 0 if the function fails.

Additional information
The ySize of the widget in closed state depends on the font used to create the widget. You can not set the ySize of a closed DROPDOWN widget.

DROPDOWN_CreateEx()

6.2.7.5.1.4
Description
Creates a DROPDOWN widget of a specified size at a specified location.

Prototype
DROPDOWN_Handle DROPDOWN_CreateEx(int x0, int y0, int xSize, int ySize, WM_HWIN hParent, int WinFlags, int ExFlags, int Id);

Parameters

Parameter Description
x0 | Leftmost pixel of the DROPDOWN widget (in parent coordinates).
y0 | Topmost pixel of the DROPDOWN widget (in parent coordinates).
xSize | Horizontal size of the DROPDOWN widget (in pixels).
ySize | Vertical size of the DROPDOWN widget in open state (in pixels).
hParent | Handle of parent window. If 0, the new DROPDOWN widget will be a child of the desktop (top-level window).
WinFlags | Window create flags. Typically WM_CF_SHOW in order to make the widget visible immediately (refer to Window create flags on page 919 for a list of available parameter values).
ExFlags | See DROPDOWN create flags on page 1093.
Id | Window ID of the widget.

返値
Handle of the created DROPDOWN widget; 0 if the function fails.

DROPDOWN_CreateIndirect()

6.2.7.5.1.5
Description
The prototype of this function is explained at the beginning of this chapter. Details can be found in the description of the function _CreateIndirect() on page 933. The element Para of the according GUI_WIDGET_CREATE_INFO structure is not used. The element Flags is used according to the parameter ExFlags of the function DROPDOWN_CreateEx().

DROPDOWN_CreateUser()

6.2.7.5.1.6
Description
Prototype explained at the beginning of the chapter as _CreateUser() on page 934. For a detailed description of the parameters the function DROPDOWN_CreateEx() can be referred to.

DROPDOWN_DecSel()

6.2.7.5.1.7
Description
Decrement the selection, moves the selection of a specified DROPDOWN widget up by one item.

Prototype
void DROPDOWN_DecSel(DROPDOWN_Handle hObj);

Parameters

Parameter | Description
hObj | Handle of DROPDOWN widget

DROPDOWN_DecSelExp()

6.2.7.5.1.8
Description
Decrements the selection of the attached LISTBOX in expanded state.

Prototype
void DROPDOWN_DecSelExp(DROPDOWN_Handle hObj);

Parameters

Parameter | Description
hObj | Handle of DROPDOWN widget

DROPDOWN_DeleteItem()

Description
Deletes the given item of the DROPDOWN widget.
Prototype
void DROPDOWN_DeleteItem(DROPDOWN_Handle hObj, unsigned int Index);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
Index	Zero based index of the item to be deleted.

Additional information
If the index is greater than the number of items < 1 the function returns immediately.

DROPDOWN_Expand()

Description
Opens the list of the DROPDOWN widget.

Prototype
void DROPDOWN_Expand(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

Additional information
The DROPDOWN list remains open until an element has been selected or the focus has been lost.

6.2.7.5.1.11 DROPDOWN_GetBkColor()
Description
Returns the background color of the given DROPDOWN widget.

Prototype
GUI_COLOR DROPDOWN_GetBkColor(DROPDOWN_Handle hObj, unsigned int Index);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

Index Index for background color. See DROPDOWN color indexes on page 1092 for a full list of permitted values.

返値
The background color used with the corresponding index value.

6.2.7.5.1.12 DROPDOWN_GetColor()
Description
Returns the color used for either the button or the arrow.

Prototype
GUI_COLOR DROPDOWN_GetColor(DROPDOWN_Handle hObj, unsigned int Index);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
Index	Index for background color. See table below.

Permitted values for parameter Index
DROPDOWN_CI_ARROW Color of small arrow within the button.
DROPDOWN_CI_BUTTON Button color.

返値
The color of the button or the arrow.

6.2.7.5.1.13 DROPDOWN_GetDefaultFont()
Description
Returns the default font of DROPDOWN widgets.

Prototype
GUI_FONT *DROPDOWN_GetDefaultFont(void);

Return value
Returns a pointer to the default font used by DROPDOWN widgets.

6.2.7.5.1.14 DROPDOWN_GetFont()
Description
Returns the font currently used by the widget.

Prototype
GUI_FONT *DROPDOWN_GetFont(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget

返値
A pointer to the currently set font.

6.2.7.5.1.15 DROPDOWN_GetItemDisabled()
Description
Returns the state of the given item.

Prototype
unsigned DROPDOWN_GetItemDisabled(DROPDOWN_Handle hObj, unsigned Index);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget
Index	Zero-based index of the item.

返値
1 if the given item is disabled
0 if not.

6.2.7.5.1.16 DROPDOWN_GetItemText()
Description
Returns the text of a specific item of the given DROPDOWN widget.

Prototype
int DROPDOWN_GetItemText(DROPDOWN_Handle hObj, unsigned Index, char * pBuffer, int MaxSize);

Parameters

Parameter Description
---|---
hObj Handle of DROPDOWN widget
Index Zero-based index of the item.
pBuffer Pointer to a char buffer which is filled with the text.
MaxSize Maximum number of chars which can be stored by pBuffer.

返値
0 成功
1 失敗

6.2.7.5.1.17 DROPDOWN_GetListbox()
Description
Returns the handle of the attached LISTBOX widget in expanded state.

Prototype
LISTBOX_Handle DROPDOWN_GetListbox(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

返値
Handle of the attached LISTBOX widget in expanded state, 0 if DROPDOWN is in collapsed state.

6.2.7.5.1.18 DROPDOWN_GetNumItems()
Description
Returns the number of items in the given DROPDOWN widget.

Prototype
int DROPDOWN_GetNumItems(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

返値
Number of items in the given DROPDOWN widget.

6.2.7.5.1.19 DROPDOWN_GetSel()
Description
Returns the number of the currently selected item in a specified DROPDOWN widget.

Prototype
int DROPDOWN_GetSel(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

返値
Number of the currently selected item.

6.2.7.5.1.20 DROPDOWN_GetSelExp()
Description
Returns the index of the currently selected item of the attached LISTBOX in expanded state.
Prototype
int DROPDOWN_GetSelExp(DROPDOWN_Handle hObj);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.

Return value
Index of the currently selected item.

6.2.7.5.1.21 DROPDOWN_GetTextColor()
Description
Returns the color used for text to be displayed.
Prototype
GUI_COLOR DROPDOWN_GetTextColor(DROPDOWN_Handle hObj, unsigned int Index);

Parameters

Parameter Description
hObj Handle of DROPDOWN widget.
Index Index for background color. See DROPDOWN color indexes
on page 1092 for a full list of permitted values.

返値
The color of the text corresponding to the given index.

6.2.7.5.1.22 DROPDOWN_GetUserData()
Description
Prototype explained at the beginning of the chapter as _GetUserData() on page 935.

6.2.7.5.1.23 DROPDOWN_IncSel()
Description
Increment the selection, moves the selection of a specified DROPDOWN widget down by one item.

Prototype
void DROPDOWN_IncSel(DROPDOWN_Handle hObj);

Parameters

Parameter Description
hObj Handle of DROPDOWN widget.

6.2.7.5.1.24 DROPDOWN_IncSelExp()
Description
Increments the selection of the attached LISTBOX in expanded state.

Prototype
void DROPDOWN_IncSelExp(DROPDOWN_Handle hObj);

Parameters

Parameter Description
hObj Handle of DROPDOWN widget.

6.2.7.5.1.25 DROPDOWN_InsertString()
Description
Inserts a string to the DROPDOWN widget at the given position.

Prototype
void DROPDOWN_InsertString( DROPDOWN_Handle hObj, const char * s, unsigned int Index);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
s	Pointer to the string to be inserted.
Index	Zero based index of the position.

Additional information
If the given index is greater than the number of items the string will be appended to the end of the dropdown list.

6.2.7.5.1.26 DROPDOWN_SetAutoScroll()
Description
Enables the automatic use of a vertical scroll bar in the DROPDOWN widget.

Prototype
void DROPDOWN_SetAutoScroll(DROPDOWN_Handle hObj, int OnOff);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
OnOff	See table below.
Permitted	values for parameter OnOff
0	Disable automatic use of a scroll bar.
1	Enable automatic use of a scroll bar.

Additional information
If enabled the DROPDOWN widget checks if all elements fits into the listbox. If not a vertical scroll bar will be added.

6.2.7.5.1.27 DROPDOWN_SetBkColor()
Before After

Description
Sets the background color of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetBkColor(DROPDOWN_Handle hObj, unsigned int Index, GUI_COLOR Color);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
Index	Index for background color. See DROPDOWN color indexes on page 1092 for a full list of permitted values.
Color	Color to be set.

Before After

Description
Sets the color of the button or the arrow of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetColor(DROPDOWN_Handle hObj, unsigned int Index, GUI_COLOR Color);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget.
Index	Index of desired item. See table below.
Color	Color to be used.

Permitted values for parameter Index
DROPDOWN_CI_ARROW Color of small arrow within the button.
DROPDOWN_CI_BUTTON Button color.

6.2.7.5.1.29 DROPDOWN_SetDefaultColor()
Description
Sets the default colors for the arrow and the button of new DROPDOWN widgets.

Prototype
GUI_COLOR DROPDOWN_SetDefaultColor(int Index, GUI_COLOR Color);

Parameters

Parameter	Description
Index	Refer to DROPDOWN_SetColor().
Color	Color to be used.

6.2.7.5.1.30 DROPDOWN_SetDefaultFont()
Description
Sets the default font used for new DROPDOWN widgets.

Prototype
void DROPDOWN_SetDefaultFont(const GUI_FONT * pFont);

Parameters

Parameter	Description
pFont	Pointer to GUI_FONT structure.

6.2.7.5.1.31 DROPDOWN_SetDefaultScrollbarColor()
Description
Sets the default colors used for the optional scroll bar in the DROPDOWN widget.
Prototype
GUI_COLOR DROPDOWN_SetDefaultScrollbarColor(int Index, GUI_COLOR Color);

Parameters

Parameter	Description
Index	Refer to DROPDOWN_SetScrollbarColor().
Color	Color to be used.

6.2.7.5.1.32 DROPDOWN_SetFont()
Description
Sets the font used to display the given DROPDOWN widget.
Prototype
void DROPDOWN_SetFont(DROPDOWN_Handle hObj, const GUI_FONT * pFont);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget
pFont	Pointer to the font.

6.2.7.5.1.33 DROPDOWN_SetItemDisabled()
Before After

Description
Sets the enabled state of the given item.
Prototype
void DROPDOWN_SetItemDisabled(DROPDOWN_Handle hObj, unsigned Index, int OnOff);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget
Index	Zero-based index of the item.
OnOff	1 for enabled, 0 for disabled.

6.2.7.5.1.34 DROPDOWN_SetItemSpacing()
Before After

Description
Sets an additional spacing below the items of the DROPDOWN widget.

Prototype
void DROPDOWN_SetItemSpacing(DROPDOWN_Handle hObj, unsigned Value);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget
Value	Number of pixels used as additional space between the items of the DROPDOWN widget.

6.2.7.5.1.35 DROPDOWN_SetListHeight()
Description
Sets the height in pixels to be used for the expanded list of the DROPDOWN widget.

Prototype
int DROPDOWN_SetListHeight(DROPDOWN_Handle hObj, unsigned Height);

Parameters

Parameter	Description
hObj	Handle of DROPDOWN widget
Height	Height to be used.

Return value
Previously used height for the DROPDOWN list in pixels.

6.2.7.5.1.36 DROPDOWN_SetScrollbarColor()

Before After

Description
Sets the colors of the optional scroll bar in the DROPDOWN widget.
Prototype
void DROPDOWN_SetScrollbarColor(DROPDOWN_Handle hObj,
unsigned Index,
GUI_COLOR Color);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
Index Index of desired item. See SCROLLBAR color indexes on
page 1931 for a full list of permitted values.
Color Color to be used.

6.2.7.5.1.37 DROPDOWN_SetScrollbarWidth()
Description
Sets the width of the scroll bars used by the list of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetScrollbarWidth(DROPDOWN_Handle hObj,
unsigned Width);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
Width Width of the scroll bar(s) used by the dropdown list of the
given DROPDOWN widget.

1085 CHAPTER 6 Widgets (window objects)

6.2.7.5.1.38 DROPDOWN_SetSel()
Description
Sets the selected item of a specified DROPDOWN widget.
Prototype
void DROPDOWN_SetSel(DROPDOWN_Handle hObj,
int Sel);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
Sel Element to be selected.

1086 CHAPTER 6 Widgets (window objects)

6.2.7.5.1.39 DROPDOWN_SetSelExp()
Description
Sets the selected item of the attached LISTBOX in expanded state.
Prototype
void DROPDOWN_SetSelExp(DROPDOWN_Handle hObj,
int Sel);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
Sel Element to be selected.

1087 CHAPTER 6 Widgets (window objects)

6.2.7.5.1.40 DROPDOWN_SetTextAlign()

Before After

Description
Sets the alignment used to display the text of the DROPDOWN widget in closed state.
Prototype
void DROPDOWN_SetTextAlign(DROPDOWN_Handle hObj,
int Align);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
Align Alignment used to display the dropdown text in closed state.

6.2.7.5.1.41 DROPDOWN_SetTextColor()
Description
Sets the background color of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetTextColor(DROPDOWN_Handle hObj,
unsigned int Index,
GUI_COLOR Color);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
Index Index for background color. See DROPDOWN color indexes
on page 1092 for a full list of permitted values.
Color Color to be set.

6.2.7.5.1.42 DROPDOWN_SetTextHeight()

Before After

Description
Sets the height of the rectangle used to display the text of DROPDOWN widget in closed
state.
Prototype
void DROPDOWN_SetTextHeight(DROPDOWN_Handle hObj,
unsigned TextHeight);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget.
TextHeight Height of the rectangle used to display the text in closed
state.
Additional information
Per default the height of the DROPDOWN widget depends on the used font. Using this
function with TextHeight > 0 means the given value should be used. TextHeight = 0
means the default behavior should be used.

1090 CHAPTER 6 Widgets (window objects)

6.2.7.5.1.43 DROPDOWN_SetUpMode()

Before After

Description
Enables opening of the list to the upper side of the DROPDOWN widget.
Prototype
int DROPDOWN_SetUpMode(DROPDOWN_Handle hObj,
int OnOff);
Parameters
Parameter Description
hObj Handle of DROPDOWN widget
OnOff 1 for enabling, 0 for disabling ’up mode’.

1091 CHAPTER 6 Widgets (window objects)

6.2.7.5.1.44 DROPDOWN_SetUserData()
Description
Prototype explained at the beginning of the chapter as _SetUserData() on
page 936.

1092 CHAPTER 6 Widgets (window objects)

6.2.7.5.2 Defines
6.2.7.5.2.1 DROPDOWN color indexes
Description
Color indexes for DROPDOWN widget.
Definition

define DROPDOWN_CI_UNSEL 0

define DROPDOWN_CI_SEL 1

define DROPDOWN_CI_SELFOCUS 2

Symbols
Definition Description
DROPDOWN_CI_UNSEL Unselected element.
DROPDOWN_CI_SEL Selected element, without focus.
DROPDOWN_CI_SELFOCUS Selected element, with focus.

6.2.7.5.2.2 DROPDOWN create flags
Description
These flags can be used when creating a DROPDOWN widget via DROPDOWN_CreateEx(). 0
can be specified for the ExFlags parameter, if no flags should be used.
Definition

define DROPDOWN_CF_AUTOSCROLLBAR (1 << 0)

define DROPDOWN_CF_UP (1 << 1)

Symbols
Definition Description
DROPDOWN_CF_AU-
TOSCROLLBAR

Enable automatic use of a scroll bar. For details, refer to
DROPDOWN_SetAutoScroll().

DROPDOWN_CF_UP

Creates a DROPDOWN widget which opens the dropdown list
above the widget. This flag is useful if the space below the
widget is not sufficient for the dropdown list.

1094 CHAPTER 6 Widgets (window objects)

6.2.7.6 Example
The Sample folder contains the following example which shows how the widget can be used:
• WIDGET_Dropdown.c
Note that several other examples also make use of this widget and may also be helpful to
get familiar with the widget.
Screenshot of WIDGET_Dropdown.c:

1095 CHAPTER 6 Widgets (window objects)

6.2.8 EDIT: Edit widget
EDIT widgets are commonly used as the primary user interface for text input:
Blank EDIT widget EDIT widget with user input

You can also use EDIT widgets for entering values in binary, decimal, or hexadecimal modes.
A decimal-mode edit field might appear similar to those in the following table. The back-
ground color of EDIT widgets by default turns gray if disabled:
EDIT widget with user input (decimal) Disabled EDIT widget

Note
All EDIT-related routines are located in the file(s) EDIT*.c, EDIT.h.
All identifiers are prefixed EDIT.

6.2.8.1 Configuration options
Type Macro Default Description
S EDIT_ALIGN_DEFAULT GUI_TA_LEFT |

GUI_TA_VCENTER Text alignment for EDIT widget.
N EDIT_BKCOLOR0_DEFAULT 0xc0c0c0 Background color, disabled state.
N EDIT_BKCOLOR1_DEFAULT GUI_WHITE Background color, enabled state.
N EDIT_BORDER_DEFAULT 1 Width of border, in pixels.
S EDIT_FONT_DEFAULT &GUI_Font13_1 Font used for edit field text.
N EDIT_TEXTCOLOR0_DEFAULT GUI_BLACK Text color, disabled state.
N EDIT_TEXTCOLOR1_DEFAULT GUI_BLACK Text color, enabled state.
N EDIT_XOFF 1 Distance in X to offset text from left
border of EDIT widget.
Available alignment flags are:
• GUI_TA_LEFT, GUI_TA_RIGHT, GUI_TA_HCENTER for horizontal alignment.
• GUI_TA_TOP, GUI_TA_BOTTOM, GUI_TA_VCENTER for vertical alignment.
6.2.8.2 Predefined IDs
The following symbols define IDs which may be used to make EDIT widgets distinguishable
from creation.

define GUI_ID_EDIT0 0x100

define GUI_ID_EDIT1 0x101

define GUI_ID_EDIT2 0x102

define GUI_ID_EDIT3 0x103

define GUI_ID_EDIT4 0x104

define GUI_ID_EDIT5 0x105

define GUI_ID_EDIT6 0x106

define GUI_ID_EDIT7 0x107

define GUI_ID_EDIT8 0x108

define GUI_ID_EDIT9 0x109

1096 CHAPTER 6 Widgets (window objects)

6.2.8.3 Notification codes
The following events are sent from an EDIT widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message Description
WM_NOTIFICATION_CLICKED Widget has been clicked.
WM_NOTIFICATION_RELEASED Widget has been released.
WM_NOTIFICATION_MOVED_OUT mWidget has been clicked and pointer has been

oved out of the widget without releasing.
WM_NOTIFICATION_VALUE_CHANGED Value (content) of the EDIT widget has
changed.
6.2.8.4 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key Reaction

GUI_KEY_UP

Increases the current character. If for example the current
character (the character below the cursor) is a ’A’ it changes
to ’B’.
GUI_KEY_DOWN cDecreases the current character. If for example the current

haracter is a ’B’ it changes to ’A’.
GUI_KEY_RIGHT Moves the cursor one character to the right.
GUI_KEY_LEFT Moves the cursor one character to the left.
GUI_KEY_BACKSPACE If the widget works in text mode, the character before the
cursor is deleted.
GUI_KEY_DELETE If the widget works in text mode, the current is deleted.

GUI_KEY_INSERT

If the widget works in text mode, this key toggles
the edit mode between GUI_EDIT_MODE_OVERWRITE
and GUI_EDIT_MODE_INSERT. For details, refer to
EDIT_SetInsertMode().
GUI_KEY_HOME Moves the cursor to its first position.
GUI_KEY_END Moves the cursor to its last position.

6.2.8.5 EDIT API
The table below lists the available emWin EDIT-related routines in alphabetical order. De-
tailed descriptions of the routines follow.
Functions
Routine Description
EDIT_AddKey() Adds user input to a specified EDIT widget.
EDIT_Create() Creates an EDIT widget. (Obsolete)
EDIT_CreateAsChild() Creates an EDIT widget as a child window. (Obso-
lete)
EDIT_CreateEx() Creates an EDIT widget.
EDIT_CreateIndirect() Creates an EDIT widget from resource table entry.
EDIT_CreateUser() Creates an EDIT widget using extra bytes as user
data.
EDIT_EnableAutoScroll() Toggles automatic text scrolling of the EDIT widget.
EDIT_EnableBlink() Enables/disables a blinking cursor
EDIT_EnableInversion() Enables/disables an inverted cursor (default is in-
verting)
EDIT_GetBkColor() Returns the background color of the EDIT widget.
EDIT_GetBorderSize() Returns the border size of an EDIT widget.
EDIT_GetCharAtPixel() Returns the character at the given pixel position.
EDIT_GetCursorCharPos() Returns the character related position of the cursor.
EDIT_GetCursorPixelPos() Returns the pixel related position of the cursor in
window coordinates.
EDIT_GetDefaultBkColor() Returns the default background color used for EDIT
widgets.
EDIT_GetDefaultFont() Returns the default font used for EDIT widgets.
EDIT_GetDefaultTextAlign() Returns the default text alignment used for EDIT
widgets.
EDIT_GetDefaultTextColor() Returns the default text color used for EDIT wid-
gets.
EDIT_GetFloatValue() Returns the current value of the EDIT widget as
floating point value.
EDIT_GetFont() Returns a pointer to the used font.

EDIT_GetMinMax()

This function is used to retrieve the minimum and
maximum value set for the EDIT widget in decimal
mode.
EDIT_GetNumChars() Returns the number of characters of the specified
EDIT widget.
EDIT_GetSel() Returns the current selection.
EDIT_GetSelText() Copies the selected text into a buffer.
EDIT_GetText() Retrieves the user input of a specified EDIT widget.
EDIT_GetTextAlign() This function returns the currently set alignment of
the EDIT widget.
EDIT_GetTextColor() Returns the text color.
EDIT_GetUserData() Retrieves the data set with EDIT_SetUserData().
EDIT_GetValue() Returns the current value of the EDIT widget.
EDIT_SetBinMode() Enables the binary edit mode of the EDIT widget.

1098 CHAPTER 6 Widgets (window objects)

Routine Description
EDIT_SetBkColor() Sets the background color of the EDIT widget.
EDIT_SetBorderSize() Sets the border size of an EDIT widget.
EDIT_SetCursorAtChar() Sets the EDIT widget cursor to a specified character
position.
EDIT_SetCursorAtPixel() Sets the EDIT widget cursor to a specified pixel po-
sition.
EDIT_SetDecMode() Enables the decimal edit mode of the EDIT widget.
EDIT_SetDefaultBkColor() Sets the default background color used for EDIT
widgets.
EDIT_SetDefaultFont() Sets the default font used for EDIT widgets.
EDIT_SetDefaultTextAlign() Sets the default text alignment for EDIT widgets.
EDIT_SetDefaultTextColor() Sets the default text color used for EDIT widgets.
EDIT_SetFloatMode() Enables the floating point edit mode of the EDIT
widget.

EDIT_SetFloatValue()

The function can be used to set the floating point
value of the EDIT widget if working in floating point
mode.
EDIT_SetFocusable() Sets focusability of the EDIT widget.
EDIT_SetFont() Sets the used font of the EDIT widget.
EDIT_SetHexMode() Enables the hexadecimal edit mode of the EDIT
widget.
EDIT_SetInsertMode() Enables or disables the insert mode of the EDIT
widget.
EDIT_SetMaxLen() eSets the maximum number of characters to be edit-

d by the given EDIT widget.
EDIT_SetpfAddKeyEx() Sets a function which is called to add a character.
EDIT_SetSel() Sets the current selection.
EDIT_SetText() Sets the text.
EDIT_SetTextAlign() Sets the text alignment of the EDIT widget.
EDIT_SetTextColor() Sets the text color of the EDIT widget.
EDIT_SetTextMode() Sets the edit mode of the EDIT widget back to text
mode.
EDIT_SetValue() Sets the current value of the EDIT widget.
EDIT_SetUlongMode() Enables the unsigned long decimal edit mode of the
EDIT widget.
EDIT_SetUserData() Sets the extra data of an EDIT widget.
Defines
Group of defines Description
EDIT color indexes Color indexes for EDIT widget.
EDIT flags Flags used for EDIT widgets.

6.2.8.5.1 Functions
6.2.8.5.1.1 EDIT_AddKey()
Description
Adds user input to a specified EDIT widget.
Prototype
void EDIT_AddKey(EDIT_Handle hObj,
int Key);
Parameters
Parameter Description
hObj Handle of EDIT widget
Key Character to be added.
Additional information
The specified character is added to the user input of the EDIT widget. If the last character
should be erased, the key GUI_KEY_BACKSPACE can be used. If the maximum count of
characters has been reached, another character will not be added.

1100 CHAPTER 6 Widgets (window objects)

6.2.8.5.1.2 EDIT_Create()

Note
This function is deprecated, EDIT_CreateEx() should be used instead.

Description
Creates an EDIT widget of a specified size at a specified location.
Prototype
EDIT_Handle EDIT_Create(int x0,
int y0,
int xSize,
int ySize,
int Id,
int MaxLen,
int Flags);
Parameters
Parameter Description
x0 Leftmost pixel of the edit field (in parent coordinates).
y0 Topmost pixel of the edit field (in parent coordinates).
xSize Horizontal size of the edit field (in pixels).
ySize Vertical size of the edit field (in pixels.
Id ID to be returned.
MaxLen Maximum count of characters.

Flags

Window create flags. Typically WM_CF_SHOW in order to make
the widget visible immediately (refer to Window create flags
on page 919 for a list of available parameter values).

Return value
Handle of the created EDIT widget; 0 if the function fails.

1101 CHAPTER 6 Widgets (window objects)

6.2.8.5.1.3 EDIT_CreateAsChild()

Note
This function is deprecated, EDIT_CreateEx() should be used instead.

Description
Creates an EDIT widget as a child window.
Prototype
EDIT_Handle EDIT_CreateAsChild(int x0,
int y0,
int xSize,
int ySize,
WM_HWIN hParent,
int Id,
int Flags,
int MaxLen);
Parameters
Parameter Description
x0 X-position of the edit field relative to the parent window.
y0 Y-position of the edit field relative to the parent window.
xSize Horizontal size of the edit field (in pixels).
ySize Vertical size of the edit field (in pixels).
hParent Handle of parent window.
Id ID to be assigned to the EDIT widget.
Flags Window create flags (see Window create flags on page 919).
MaxLen Maximum count of characters.
Return value
Handle of the created EDIT widget; 0 if the function fails.

6.2.8.5.1.4 EDIT_CreateEx()
Description
Creates an EDIT widget of a specified size at a specified location.
Prototype
EDIT_Handle EDIT_CreateEx(int x0, int y0, int xSize, int ySize, WM_HWIN hParent, int WinFlags, int ExFlags, int Id, int MaxLen);

Parameters
Parameter Description
x0 Leftmost pixel of the widget (in parent coordinates).
y0 Topmost pixel of the widget (in parent coordinates).
xSize Horizontal size of the widget (in pixels).
ySize Vertical size of the widget (in pixels).
hParent Handle of parent window. If 0, the new EDIT widget will be a
child of the desktop (top-level window).

WinFlags

Window create flags. Typically WM_CF_SHOW in order to make the widget visible immediately (refer to Window create flags on page 919 for a list of available parameter values).
ExFlags Not used, reserved for future use.
Id Window ID of the widget.
MaxLen Maximum count of characters.

Return value
Handle of the created EDIT widget; 0 if the function fails.

EDIT_CreateIndirect()

6.2.8.5.1.5
Description
The prototype of this function is explained at the beginning of this chapter. Details can
be found in the description of the function _CreateIndirect() on page 933.
The element Flags is used according to the parameter Align of the function EDIT_SetTextAlign(). The element Para is used according to the parameter MaxLen of the function EDIT_CreateEx().

6.2.8.5.1.6 EDIT_CreateUser()
Description
Prototype explained at the beginning of the chapter as _CreateUser() on
page 934. For a detailed description of the parameters the function EDIT_CreateEx() can
be referred to.

6.2.8.5.1.7 EDIT_EnableAutoScroll()
Description
Toggles automatic text scrolling of the EDIT widget. With this mode, when text is entered
or deleted and the cursor moves out of the widget, the text is automatically scrolled so
that the cursor remains visible.
Prototype
void EDIT_EnableAutoScroll(EDIT_Handle hObj,
int OnOff);
Parameters
Parameter Description
hObj Handle of EDIT widget.
OnOff 1 enables automatic scrolling, 0 disables it.
Additional information
Automatic text scrolling is enabled by default.

6.2.8.5.1.8 EDIT_EnableBlink()
Description
Enables/disables a blinking cursor.
Prototype
void EDIT_EnableBlink(EDIT_Handle hObj,
int Period,
int OnOff);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Period Blinking period
OnOff 1 enables blinking, 0 disables blinking
Additional information
This function calls GUI_X_GetTime().

6.2.8.5.1.9 EDIT_EnableInversion()
Description
Toggles between inversion mode.
Prototype
int EDIT_EnableInversion(EDIT_Handle hObj,
int OnOff);
Parameters
Parameter Description
hObj Handle of EDIT widget.
OnOff 1 enables inverting, 0 disables inverting
Return value
Previous used mode.
0 No inversion.
1 Inversion mode.
Additional information
The text cursor per default is drawn by inverting the character which is currently edited. If a
cursor with a dedicated text- and background color is required, inversion can be deactivated
and the functions EDIT_SetTextColor() and EDIT_SetBkColor() may be used for setting
the cursor color.

6.2.8.5.1.10 EDIT_GetBkColor()
Description
Returns the background color of the EDIT widget.
Prototype
GUI_COLOR EDIT_GetBkColor(EDIT_Handle hObj,
unsigned int Index);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Index Color index. See EDIT color indexes on page 1153 for a full
list of permitted values.
Return value
Background color of the EDIT widget.

6.2.8.5.1.11 EDIT_GetBorderSize()
Description
Returns the border size of an EDIT widget.
Prototype
int EDIT_GetBorderSize(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
= -1 Error.
≠ -1 Border size of the EDIT widget.

6.2.8.5.1.12 EDIT_GetCharAtPixel()
Description
Returns the character at the given pixel position.
Prototype
U16 EDIT_GetCharAtPixel(EDIT_Handle hObj, int x, int y, int * pIndex);

Parameters
Parameter Description
hObj Handle of EDIT widget.
x X-position.
y Y-position.
pIndex Pointer to int. Zero-based position of the character in the
string. Can be NULL if not needed.

Return value
= 0 No character found.
≠ 0 The character at the given pixel position.

6.2.8.5.1.13 EDIT_GetCursorCharPos()
Description
Returns the character related position of the cursor.

Prototype
int EDIT_GetCursorCharPos(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
Character related position of the cursor.
Additional information
The widget returns the character position if it has the focus or not. This means the cursor
position is also returned, if the cursor is currently not visible in the widget.

6.2.8.5.1.14 EDIT_GetCursorPixelPos()
Description
Returns the pixel related position of the cursor in window coordinates.
Prototype
void EDIT_GetCursorPixelPos(EDIT_Handle hObj,
int * pxPos,
int * pyPos);
Parameters
Parameter Description
hObj Handle of EDIT widget.
pxPos Pointer to integer variable for the X-position in window coor-
dinates.
pyPos Pointer to integer variable for the Y-position in window coor-
dinates.
Additional information
The widget returns the pixel position if it has the focus or not. This means the cursor position
is also returned, if the cursor is currently not visible in the widget.

6.2.8.5.1.15 EDIT_GetDefaultBkColor()
Description
Returns the default background color used for EDIT widgets.
Prototype
GUI_COLOR EDIT_GetDefaultBkColor(unsigned int Index);
Parameters
Parameter Description
Index Color index. See table below.
Return value
Default background color used for EDIT widgets.

6.2.8.5.1.16 EDIT_GetDefaultFont()
Description
Returns the default font used for EDIT widgets.
Prototype
GUI_FONT *EDIT_GetDefaultFont(void);
Return value
Default font used for EDIT widgets.

6.2.8.5.1.17 EDIT_GetDefaultTextAlign()
Description
Returns the default text alignment used for EDIT widgets.
Prototype
int EDIT_GetDefaultTextAlign(void);
Return value
Default text alignment used for EDIT widgets.

6.2.8.5.1.18 EDIT_GetDefaultTextColor()
Description
Returns the default text color used for EDIT widgets.
Prototype
GUI_COLOR EDIT_GetDefaultTextColor(unsigned int Index);
Parameters
Parameter Description
Index Has to be 0, reserved for future use.
Return value
Default text color used for EDIT widgets.

6.2.8.5.1.19 EDIT_GetFloatValue()
Description
Returns the current value of the EDIT widget as floating point value.
Prototype
float EDIT_GetFloatValue(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
The current value.
Additional information
The use of this function makes only sense if the edit field is in floating point edit mode.

6.2.8.5.1.20 EDIT_GetFont()
Description
Returns a pointer to the used font.
Prototype
GUI_FONT *EDIT_GetFont(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
Pointer to the used font.

6.2.8.5.1.21 EDIT_GetMinMax()
Description
This function is used to retrieve the minimum and maximum value set for the EDIT widget
in decimal mode.
Prototype
void EDIT_GetMinMax(EDIT_Handle hObj, int * pMin, int * pMax);

Parameters
Parameter Description
hObj Handle of EDIT widget.
pMin Pointer to retrieve the minimum value.
pMax Pointer to retrieve the maximum value.
Additional information
This function works only for an EDIT widget used in decimal mode that has a minimum and
a maximum value set. Otherwise pMin and pMax are getting set to 0.

6.2.8.5.1.22 EDIT_GetNumChars()
Description
Returns the number of characters of the specified EDIT widget.

Prototype
int EDIT_GetNumChars(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
Number of characters of the specified EDIT widget.

1121 CHAPTER 6 Widgets (window objects)

6.2.8.5.1.23 EDIT_GetSel()
Description
Returns the current selection.
Prototype
void EDIT_GetSel(EDIT_Handle hObj, int * pFirstChar, int * pLastChar);

Parameters
Parameter Description
hObj Handle of EDIT widget.
pFirstChar Pointer to an int where the number of the first selected char
will be stored in.
pLastChar Pointer to an int where the number of the last selected char
will be stored in.

1122 CHAPTER 6 Widgets (window objects)

6.2.8.5.1.24 EDIT_GetSelText()
Description
Copies the selected text into a buffer.
Prototype
void EDIT_GetSelText(EDIT_Handle hObj, char * sDest, int MaxLen);

Parameters
Parameter Description
hObj Handle of EDIT widget.
sDest Pointer to buffer.
MaxLen Size of buffer.

1123 CHAPTER 6 Widgets (window objects)

6.2.8.5.1.25 EDIT_GetText()
Description
Retrieves the user input of a specified EDIT widget.
Prototype
void EDIT_GetText(EDIT_Handle hObj,
char * sDest,
int MaxLen);
Parameters
Parameter Description
hObj Handle of EDIT widget.
sDest Pointer to buffer.
MaxLen Size of buffer.

6.2.8.5.1.26 EDIT_GetTextAlign()
Description
This function returns the currently set alignment of the EDIT widget.
Prototype
int EDIT_GetTextAlign(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
The currently set text alignment for the given EDIT widget.

6.2.8.5.1.27 EDIT_GetTextColor()
Description
Returns the text color.
Prototype
GUI_COLOR EDIT_GetTextColor(EDIT_Handle hObj,
unsigned int Index);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Index Color index. See EDIT color indexes on page 1153 for a full
list of permitted values.
Return value
The currently set text color.

6.2.8.5.1.28 EDIT_GetUserData()
Description
Prototype explained at the beginning of the chapter as _GetUserData() on
page 935.

6.2.8.5.1.29 EDIT_GetValue()
Description
Returns the current value of the EDIT widget. The current value is only useful if the EDIT
widget is in binary, decimal or hexadecimal mode.
Prototype
I32 EDIT_GetValue(EDIT_Handle hObj);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Return value
The current value.

6.2.8.5.1.30 EDIT_SetBinMode()
Description
Enables the binary edit mode of the EDIT widget. The given value can be modified in the
given range.
Prototype
void EDIT_SetBinMode(EDIT_Handle hEdit, U32 Value, U32 Min, U32 Max);

Parameters
Parameter Description
hObj Handle of EDIT widget.
Value Value to be modified.
Min Minimum value.
Max Maximum value.

6.2.8.5.1.31 EDIT_SetBkColor()
Description
Sets the background color of the EDIT widget.
Prototype
void EDIT_SetBkColor(EDIT_Handle hObj,
unsigned int Index,
GUI_COLOR Color);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Index Color index. See EDIT color indexes on page 1153 for a full
list of permitted values.
Color Color to be set.

6.2.8.5.1.32 EDIT_SetCursorAtChar()
Description
Sets the EDIT widget cursor to a specified character position.
Prototype
void EDIT_SetCursorAtChar(EDIT_Handle hObj,
int Pos);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Pos Character position to set cursor to.
Additional information
The character position works as follows:
0: left of the first (leftmost) character,
1: between the first and second characters,
2: between the second and third characters, and so on.

6.2.8.5.1.33 EDIT_SetCursorAtPixel()
Description
Sets the EDIT widget cursor to a specified pixel position.
Prototype
void EDIT_SetCursorAtPixel(EDIT_Handle hObj,
int xPos);
Parameters
Parameter Description
hObj Handle of EDIT widget.
xPos Pixel position to set cursor to.

6.2.8.5.1.34 EDIT_SetDecMode()
Description
Enables the decimal edit mode of the EDIT widget. The given value can be modified in the
given range.
Prototype
void EDIT_SetDecMode(EDIT_Handle hEdit,
I32 Value,
I32 Min,
I32 Max,
int Shift,
U8 Flags);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Value Value to be set.
Min Minimum value.
Max Maximum value.
Shift If > 0 it specifies the position of the decimal point.
Flags See EDIT flags on page 1154 for a full list of permitted val-
ues.

6.2.8.5.1.35 EDIT_SetDefaultBkColor()
Description
Sets the default background color used for EDIT widgets.
Prototype
void EDIT_SetDefaultBkColor(unsigned int Index,
GUI_COLOR Color);
Parameters
Parameter Description
Index Color index. See table below.
Color Color to be used.

6.2.8.5.1.36 EDIT_SetDefaultFont()
Description
Sets the default font used for EDIT widgets.
Prototype
void EDIT_SetDefaultFont(const GUI_FONT * pFont);
Parameters
Parameter Description
pFont Pointer to the font to be set as default.

6.2.8.5.1.37 EDIT_SetDefaultTextAlign()
Description
Sets the default text alignment for EDIT widgets.
Prototype
void EDIT_SetDefaultTextAlign(int Align);
Parameters
Parameter Description
Align Default text alignment. For details, refer to EDIT_SetTex-
tAlign().

6.2.8.5.1.38 EDIT_SetDefaultTextColor()
Description
Sets the default text color used for EDIT widgets.
Prototype
void EDIT_SetDefaultTextColor(unsigned int Index, GUI_COLOR Color);

Parameters
Parameter Description
Index Has to be 0, reserved for future use.
Color Color to be used.

6.2.8.5.1.39 EDIT_SetFloatMode()
Description
Enables the floating point edit mode of the EDIT widget. The given value can be modified
in the given range.
Prototype
void EDIT_SetFloatMode(EDIT_Handle hEdit, float Value, float Min, float Max, int Shift, U8 Flags);

Parameters
Parameter Description
hObj Handle of EDIT widget.
Value Value to be modified.
Min Minimum value.
Max Maximum value.
Shift Number of post decimal positions.
Flags See EDIT flags on page 1154 for a full list of permitted val-
ues.

Additional information
The float calculation of the EDIT widget is based on 32 bit signed integer calculation. If
using 4 decimal places, the values have to be internally multiplied with 104. That exceeds
the range of 231. Editing values with 9 digits (before and after decimal point) will work.

6.2.8.5.1.40 EDIT_SetFloatValue()
Description
The function can be used to set the floating point value of the EDIT widget if working in
floating point mode.

Prototype
void EDIT_SetFloatValue(EDIT_Handle hObj, float Value);

Parameters
Parameter Description
hObj Handle of EDIT widget.
Value New floating point value of the EDIT widget.

Additional information
The use of this function makes only sense if the EDIT widget works in floating point mode. If working in text mode the function has no effect. If working in binary, decimal or hexadecimal mode the behavior of the EDIT widget is undefined.

6.2.8.5.1.41 EDIT_SetFocusable()
Description
Sets the focusability of the EDIT widget.

Prototype
void EDIT_SetFocusable(EDIT_Handle hObj, int State);

Parameter Description
hObj Handle of EDIT widget.
State If State is set to 0, the EDIT widget is set not to be focus-
able. Otherwise it is set to be focusable.

6.2.8.5.1.42 EDIT_SetFont()
Description
Sets the used font of the EDIT widget.
Prototype
void EDIT_SetFont(EDIT_Handle hObj, const GUI_FONT * pFont);
Parameters
Parameter Description
hObj Handle of EDIT widget.
pFont Pointer to the font.

6.2.8.5.1.43 EDIT_SetHexMode()
Description
Enables the hexadecimal edit mode of the EDIT widget. The given value can be modified
in the given range.
Prototype
void EDIT_SetHexMode(EDIT_Handle hEdit, U32 Value, U32 Min, U32 Max);

Parameters
Parameter Description
hObj Handle of EDIT widget.
Value Value to be modified.
Min Minimum value.
Max Maximum value.

6.2.8.5.1.44 EDIT_SetInsertMode()
Description
Enables or disables the insert mode of the EDIT widget.
Prototype
int EDIT_SetInsertMode(EDIT_Handle hObj, int OnOff);

Parameters
Parameter Description
hObj Handle of EDIT widget.
OnOff 0 for disabling insert mode, 1 for enabling insert mode.

Return value
Returns the previous insert mode state.

Additional information
The use of this function makes only sense if the EDIT widget operates in text mode or in any user defined mode. If working in hexadecimal, binary, floating point or decimal mode the use of this function has no effect except that it changes the appearance of the cursor.

6.2.8.5.1.45 EDIT_SetMaxLen()
Description
Sets the maximum number of characters to be edited by the given EDIT widget.
Prototype
void EDIT_SetMaxLen(EDIT_Handle hObj,
int MaxLen);
Parameters
Parameter Description
hObj Handle of EDIT widget.
MaxLen Number of characters.

6.2.8.5.1.46 EDIT_SetpfAddKeyEx()
Description
Sets the function pointer which is used by the EDIT widget to call the function which is
responsible for adding characters.
Prototype
void EDIT_SetpfAddKeyEx(EDIT_Handle hObj,
tEDIT_AddKeyEx * pfAddKeyEx);
Parameters
Parameter Description
hObj Handle of EDIT widget.
pfAddKeyEx Function pointer to the function to be used to add a charac-
ter.
Additional information
If working in text mode (default) or one of the modes for editing values, the EDIT widget
uses its own routines to add a character. The use of this function only makes sense if the
default behavior of the EDIT widget needs to be changed. If a function pointer has been set
with this function the application program is responsible for the content of the text buffer.

6.2.8.5.1.47 EDIT_SetSel()

Before After

Description
Used to set the current selection of the EDIT widget.
Prototype
void EDIT_SetSel(EDIT_Handle hObj,
int FirstChar,
int LastChar);
Parameters
Parameter Description
hObj Handle of EDIT widget.
FirstChar Zero based index of the first character to be selected. -1 if
no character should be selected.

LastChar

Zero based index of the last character to be selected. -1 if
all characters from the first character until the last character
should be selected.

Additional information
Selected characters are usually displayed in reverse. Setting the cursor position deselects
all characters.
Example

EDIT_SetSel(hEdit, 0, -1); // Selects all characters of the widget
EDIT_SetSel(hEdit, -1, 0); // Deselects all characters
EDIT_SetSel(hEdit, 0, 2); // Selects the first 3 characters

6.2.8.5.1.48 EDIT_SetText()
Description
Sets the text to be displayed in the EDIT widget.
Prototype
void EDIT_SetText( EDIT_Handle hObj,
const char * s);
Parameters
Parameter Description
hObj Handle of EDIT widget.
s Text to display.

6.2.8.5.1.49 EDIT_SetTextAlign()
Description
Sets the text alignment of the EDIT widget.
Prototype
void EDIT_SetTextAlign(EDIT_Handle hObj,
int Align);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Align Or-combination of text alignment flags. List of flags can be
found under Text alignment flags on page 238.

6.2.8.5.1.50 EDIT_SetTextColor()
Description
Sets the text color of the EDIT widget.
Prototype
void EDIT_SetTextColor(EDIT_Handle hObj,
unsigned int Index,
GUI_COLOR Color);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Index Index for text color. See EDIT color indexes on page 1153
for a full list of permitted values.
Color Color to be set.

6.2.8.5.1.51 EDIT_SetTextMode()
Description
Sets the edit mode of the EDIT widget back to text mode.
Prototype
void EDIT_SetTextMode(EDIT_Handle hEdit);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Additional information
If one of the functions EDIT_SetBinMode(), EDIT_SetDecMode(), EDIT_SetFloatMode()
or EDIT_SetHexMode() has been used to set the EDIT widget to one of the numeric edit
modes, this function sets the edit mode back to text mode. It also clears the content of
the EDIT widget.

6.2.8.5.1.52 EDIT_SetValue()
Description
Sets the current value of the EDIT widget. Only useful if binary, decimal or hexadecimal
edit mode is set.
Prototype
void EDIT_SetValue(EDIT_Handle hObj,
I32 Value);
Parameters
Parameter Description
hObj Handle of EDIT widget.
Value New value.

6.2.8.5.1.53 EDIT_SetUlongMode()
Description
Enables the unsigned long decimal edit mode of the EDIT widget. The given value can be
modified in the given range.
Prototype
void EDIT_SetUlongMode(EDIT_Handle hEdit, U32 Value, U32 Min, U32 Max);

Parameters
Parameter Description
hObj Handle of EDIT widget.
Value Value to be modified.
Min Minimum value.
Max Maximum value.

1152 CHAPTER 6 Widgets (window objects)

6.2.8.5.1.54 EDIT_SetUserData()
Description
Prototype explained at the beginning of the chapter as _SetUserData() on
page 936.

6.2.8.5.2 Defines
6.2.8.5.2.1 EDIT color indexes
Description
Color indexes for EDIT widget.
Definition

define EDIT_CI_DISABLED 0

define EDIT_CI_ENABLED 1

define EDIT_CI_CURSOR 2

Symbols
Definition Description
EDIT_CI_DISABLED Color index for the disabled state.
EDIT_CI_ENABLED Color index for the enabled state.

EDIT_CI_CURSOR

Color to be used for the cursor. This is only taken into ac-
count if the cursor is not in inversion mode (EDIT_EnableIn-
version(0)).

6.2.8.5.2.2 EDIT flags
Description
These flags are used if the EDIT widget is in decimal or float mode. This can be activated
by calling EDIT_SetDecMode() or EDIT_SetFloatMode(). These flags are OR-combinable.
Definition

define GUI_EDIT_NORMAL (0 << 0)

define GUI_EDIT_SIGNED (1 << 0)

define GUI_EDIT_SUPPRESS_LEADING_ZEROES (1 << 1)

Symbols
Definition Description
GUI_EDIT_NORMAL Edit in normal mode. A sign is displayed only if the value is
negative.
GUI_EDIT_SIGNED “+” and “-” sign is displayed.
GUI_EDIT_SUP-
PRESS_LEADING_ZEROES Does not show leading zeroes.

6.2.8.6 Examples
The Sample folder contains the following examples which show how the widget can be used:
• WIDGET_Edit.c
• WIDGET_EditWinmode.c
Note that several other examples also make use of this widget and may also be helpful to
get familiar with the widget.
Screenshot of WIDGET_Edit.c:

Screenshot of WIDGET_EditWinmode.c:

FRAMEWIN: Frame window widget

6.2.9
FRAMEWIN widgets give your application a PC application-window appearance. They consist
of a surrounding frame, a title bar and a user area. The color of the title bar changes to
show whether the window is active or inactive, as seen below:
Active frame window Inactive frame window

Note
All FRAMEWIN-related routines are located in the file(s) FRAMEWIN*.c, FRAMEWIN.h.
All identifiers are prefixed FRAMEWIN.
You can attach predefined buttons to the title bar as seen below or you can attach your
own buttons to a title bar:
Description Frame window

Frame window with minimize-, maximize-
and close button.

Frame window with minimize-, maximize-
and close button in maximized state.

Frame window with minimize-, maximize-
and close button in minimized state
Skinning...

…is available for this widget. The screenshot above shows the widget using the default skin.
Details can be found in the chapter Skinning on page 2275.

Structure of the frame window

6.2.9.1
The following diagram shows the detailed structure and looks of a frame window:

The frame window actually consists of 2 windows; the main window and a child window. The
child window is called Client window. It is important to be aware of this when dealing with
callback functions: There are 2 windows with 2 different callback functions. When creating
child windows, these child windows are typically created as children of the client window;
their parent is therefor the client window.
Detail Description
B Border size of the frame window. The default size of the bor-
der is 3 pixels.
H Height of the title bar. Depends on the size of the used font
for the title.
D Spacing between title bar and client window. (1 pixel)
Title bar The title bar is part of the frame window and not a separate
window.
Client window wThe client window is a separate window created as a child

6.2.9.2 Configuration options
Type Macro Default Description
B FRAMEWIN_ALLOW_DRAG_ON_FRAME 1 Allows dragging the widget
on the surrounding frame.
N FRAMEWIN_BARCOLOR_ACTIVE_DEFAULT 0xff0000 Title bar background color,
active state.
N FRAMEWIN_BARCOLOR_INACTIVE_DEFAULT 0x404040 Title bar background color,
inactive state.
N FRAMEWIN_BORDER_DEFAULT 3 Outer border width, in pix-
els.

FRAMEWIN_CLIENTCOLOR_DEFAULT
(with WIDGET_USE_FLEX_SKIN = 0)
(with WIDGET_USE_FLEX_SKIN = 1)

0xc0c0c0
GUI_WHITE Color of client window area.

FRAMEWIN_DEFAULT_FONT
(with WIDGET_USE_FLEX_SKIN = 0)
(with WIDGET_USE_FLEX_SKIN = 1)

&GUI_Font8_1
&GUI_Font13_1 Font used for title bar text.
N FRAMEWIN_FRAMECOLOR_DEFAULT 0xaaaaaa Frame color.
N FRAMEWIN_IBORDER_DEFAULT 1 Inner border width, in pix-
els.

FRAMEWIN_TEXTCOLOR_ACTIVE_DEFAULT
(with WIDGET_USE_FLEX_SKIN = 0)
(with WIDGET_USE_FLEX_SKIN = 1)

GUI_WHITE
GUI_BLACK

Title bar text color, active
state.

FRAMEWIN_TEXTCOLOR_INACTIVE_DEFAULT
(with WIDGET_USE_FLEX_SKIN = 0)
(with WIDGET_USE_FLEX_SKIN = 1)

GUI_WHITE
GUI_BLACK

Title bar text color, inactive
state.
N FRAMEWIN_TITLEHEIGHT_DEFAULT 0 Default height of title bar.

6.2.9.3 Keyboard reaction
The widget can not gain the input focus and does not react on keyboard input.
6.2.9.4 FRAMEWIN API
The table below lists the available emWin FRAMEWIN-related routines in alphabetical order.
Detailed descriptions of the routines follow.
Functions
Routine Description
FRAMEWIN_AddButton() Adds a button to the title bar of the
FRAMEWIN widget.
FRAMEWIN_AddCloseButton() Adds a close button to the title bar of the
FRAMEWIN widget.
FRAMEWIN_AddMaxButton() Adds a maximize button to the title bar of
the FRAMEWIN widget.
FRAMEWIN_AddMenu() Adds the given menu to a FRAMEWIN wid-
get.
FRAMEWIN_AddMinButton() Adds a minimize button to the title bar of
the FRAMEWIN widget.
FRAMEWIN_Create() Creates a FRAMEWIN widget. (Obsolete)
FRAMEWIN_CreateAsChild() Creates a FRAMEWIN widget as a child
window. (Obsolete)

Routine Description
FRAMEWIN_CreateEx() Creates a FRAMEWIN widget.
FRAMEWIN_CreateIndirect() Creates a FRAMEWIN widget from a re-
source table entry.
FRAMEWIN_CreateUser() bCreates a FRAMEWIN widget using extra

ytes as user data.
FRAMEWIN_GetActive() Returns if the given FRAMEWIN widget is
in active state or not.
FRAMEWIN_GetBarColor() Returns the color of the title bar of the giv-
en FRAMEWIN widget.
FRAMEWIN_GetBorderSize() Returns the border size of the given
FRAMEWIN widget.
FRAMEWIN_GetDefaultBarColor() Returns the default color for title bars in
FRAMEWIN widgets.
FRAMEWIN_GetDefaultBorderSize() Returns the default border size of
FRAMEWIN widgets.
FRAMEWIN_GetDefaultClientColor() Returns the default color of client areas in
FRAMEWIN widgets.
FRAMEWIN_GetDefaultFont() Returns the default font used for captions
of FRAMEWIN widgets.
FRAMEWIN_GetDefaultTextColor() Returns the default text color of the title.
FRAMEWIN_GetDefaultTitleHeight() Returns the default height of title bars in
FRAMEWIN widget.
FRAMEWIN_GetFont() Returns a pointer to the font used to draw
the title text.
FRAMEWIN_GetText() Returns the title text.
FRAMEWIN_GetTextAlign() Returns the text alignment of the title text.
FRAMEWIN_GetTitleHeight() Returns the height of title bar of the given
FRAMEWIN widget.
FRAMEWIN_GetUserData() Retrieves the data set with FRAMEWIN_Se-
tUserData().
FRAMEWIN_IsMinimized() Returns if the FRAMEWIN widget is mini-
mized or not.
FRAMEWIN_IsMaximized() Returns if the FRAMEWIN widget is maxi-
mized or not.
FRAMEWIN_Maximize() Enlarges a FRAMEWIN widget to the size of
its parent window.
FRAMEWIN_Minimize() Hides the client area of the given
FRAMEWIN widget.
FRAMEWIN_OwnerDraw() aDefault function for drawing the title bar of

FRAMEWIN widget.

FRAMEWIN_Restore()

Restores a minimized or maximized
FRAMEWIN widget to its old size and posi-
tion.
FRAMEWIN_SetActive() Sets the state of a specified FRAMEWIN
widget.
FRAMEWIN_SetBarColor() Sets the color of the title bar of a specified
FRAMEWIN widget.
FRAMEWIN_SetBorderSize() Sets the border size of a specified
FRAMEWIN widget.

Routine Description
FRAMEWIN_SetClientColor() aSets the color of the client window area of

specified FRAMEWIN widget.
FRAMEWIN_SetDefaultBarColor() Sets the default color for title bars in
FRAMEWIN widgets.
FRAMEWIN_SetDefaultBorderSize() Sets the default border size of FRAMEWIN
widgets.
FRAMEWIN_SetDefaultClientColor() Sets the default color for client areas in
FRAMEWIN widgets.
FRAMEWIN_SetDefaultFont() Sets the default font used to display the ti-
tle in FRAMEWIN widgets.
FRAMEWIN_SetDefaultTextColor() Sets the default text color of the title.
FRAMEWIN_SetDefaultTitleHeight() Sets the size in Y for the title bar.
FRAMEWIN_SetFont() Sets the title font of the FRAMEWIN wid-
get.
FRAMEWIN_SetMoveable() fSets a FRAMEWIN widget to a moveable or

ixed state.
FRAMEWIN_SetOwnerDraw() dEnables the FRAMEWIN widget to be owner rawn.
FRAMEWIN_SetResizeable() Sets the resizable state of the given FRAMEWIN widget.
FRAMEWIN_SetText() Sets the title text.
FRAMEWIN_SetTextAlign() Sets the text alignment of the title bar.
FRAMEWIN_SetTextColor() Sets the color of the title text for both states, active and inactive.
FRAMEWIN_SetTextColorEx() Sets the text color for the given state.
FRAMEWIN_SetTitleHeight() Sets the height of the title bar.
FRAMEWIN_SetTitleVis() Sets the visibility flag of the title bar.
FRAMEWIN_SetUserData() Sets the extra data of a FRAMEWIN widget.
Defines
Group of defines Description
FRAMEWIN button flags Determine on which side of the FRAMEWIN a button
should be added.
FRAMEWIN create flags Create flags that define the behavior of the FRAMEWIN widget.
FRAMEWIN states State of the FRAMEWIN used for various functions.

Functions

6.2.9.4.1

FRAMEWIN_AddButton()

6.2.9.4.1.1
Before After

Description
Adds a button to the title bar of the FRAMEWIN widget.
Prototype
WM_HWIN FRAMEWIN_AddButton(FRAMEWIN_Handle hObj, int Flags, int Off, int Id);

Return value
Handle of the BUTTON widget.

Additional information
The button will be created as a child window from the FRAMEWIN widget. So the Window Manager keeps sure it will be deleted when the FRAMEWIN widget will be deleted.
The button can be created at the left side or at the right side of the title bar depending on the parameter Flags. The parameter Offset specifies the space between the button and the border of the FRAMEWIN widget or the space between the previous created button.

6.2.9.4.1.2 FRAMEWIN_AddCloseButton()

Before After

Description
Adds a close button to the title bar of the FRAMEWIN widget.
Prototype
WM_HWIN FRAMEWIN_AddCloseButton(FRAMEWIN_Handle hObj, int Flags, int Off);

Parameters
Parameter Description
hObj Handle of FRAMEWIN widget.
Flags See FRAMEWIN button flags on page 1213 for a full list of
permitted values.
Off X-offset used to create the BUTTON widget
Return value
Handle of the close button.
Additional information
When the user presses the close button the frame window and all its children will be deleted.

6.2.9.4.1.3 FRAMEWIN_AddMaxButton()

Before After Maximized

Description
Adds a maximize button to the title bar of the FRAMEWIN widget.
Prototype
WM_HWIN FRAMEWIN_AddMaxButton(FRAMEWIN_Handle hObj, int Flags, int Off);

Parameters
Parameter Description
hObj Handle of FRAMEWIN widget.
Flags See FRAMEWIN button flags on page 1213 for a full list of
permitted values.
Off X-offset used to create the BUTTON widget

Return value
Handle of the maximize button.

Additional information
When the user presses the maximize button the first time the FRAMEWIN widget will be enlarged to the size of its parent window. The second use of the button will reduce the frame window to its old size and restores the old position.

6.2.9.4.1.4 FRAMEWIN_AddMenu()

Before After

Description
Adds the given menu to a FRAMEWIN widget. The menu is shown below the title bar.

Prototype
void FRAMEWIN_AddMenu(FRAMEWIN_Handle hObj, WM_HWIN hMenu);

Parameters
Parameter Description
hObj Handle of frame window.
hMenu Handle of MENU widget to be added.

Return value
Handle of the maximize button.

Additional information
The added MENU is attached as a child of the FRAMEWIN widget. If the FRAMEWIN widget has been created with a callback routine, the function makes sure, that the WM_MENU messages are passed to the client window of the FRAMEWIN widget.

6.2.9.4.1.5 FRAMEWIN_AddMinButton()

Before After Maximized

Description
Adds a minimize button to the title bar of the FRAMEWIN widget.

Prototype
WM_HWIN FRAMEWIN_AddMinButton(FRAMEWIN_Handle hObj, int Flags, int Off);

Parameters
Parameter Description
hObj Handle of FRAMEWIN widget.
Flags See FRAMEWIN button flags on page 1213 for a full list of permitted values.
Off X-offset used to create the BUTTON widget

Return value
Handle of the minimize button.

Additional information
When the user presses the minimize button the first time the client area of the FRAMEWIN
widget will be hidden and only the title bar remains visible. The second use of the button will restore the FRAMEWIN widget to its old size.

FRAMEWIN_Create()

6.2.9.4.1.6
Note
This function is deprecated, FRAMEWIN_CreateEx() should be used instead.

Description
Creates a FRAMEWIN widget of a specified size at a specified location.
Prototype
FRAMEWIN_Handle FRAMEWIN_Create(const char * pText,
WM_CALLBACK * cb,
int Flags,
int x0,
int y0,
int xSize,
int ySize);
Parameters
Parameter Description
pTitle Title displayed in the title bar.
cb Pointer to callback routine of client area.

Flags

Window create flags. Typically WM_CF_SHOW in order to make
the widget visible immediately (refer to Window create flags
on page 919 for a list of available parameter values).
x0 Leftmost pixel of the frame window (in parent coordinates).
y0 Topmost pixel of the frame window (in parent coordinates).
xSize Horizontal size of the frame window (in pixels).
ySize Vertical size of the frame window (in pixels).
Return value
Handle of the created FRAMEWIN widget; 0 if the function fails.

FRAMEWIN_CreateAsChild()

6.2.9.4.1.7
Note
This function is deprecated, FRAMEWIN_CreateEx() should be used instead.

Description
Creates a FRAMEWIN widget as a child window.

Prototype
FRAMEWIN_Handle FRAMEWIN_CreateAsChild(int x0, int y0, int xSize, int ySize, WM_HWIN hParent, const char * pText, WM_CALLBACK * cb, int Flags);

Parameters
Parameter Description
x0 X-position of the FRAMEWIN widget relative to the parent window.
y0 Y-position of the FRAMEWIN widget relative to the parent window.
xSize Horizontal size of the FRAMEWIN widget (in pixels).
ySize Vertical size of the FRAMEWIN widget (in pixels).
hParent Handle of parent window.
pText Text to be displayed in the title bar.
cb Optional pointer to a custom callback function for the client window.
Flags Window create flags (see Window create flags on page 919).

Return value
Handle of the created FRAMEWIN widget; 0 if the function fails.

FRAMEWIN_CreateEx()

6.2.9.4.1.8
Description
Creates a FRAMEWIN widget of a specified size at a specified location.

Prototype
FRAMEWIN_Handle FRAMEWIN_CreateEx( int x0, int y0, int xSize, int ySize, WM_HWIN hParent, int WinFlags, int ExFlags, int Id, const char * pTitle, WM_CALLBACK * cb);

Parameters
Parameter Description
x0 Leftmost pixel of the FRAMEWIN widget (in parent coordinates).
y0 Topmost pixel of the FRAMEWIN widget (in parent coordinates).
xSize Horizontal size of the FRAMEWIN widget (in pixels).
ySize Vertical size of the FRAMEWIN widget (in pixels).
hParent Handle of parent window. If 0, the new FRAMEWIN widget will be a child of the desktop (top-level window).

WinFlags

Window create flags. Typically WM_CF_SHOW in order to make the widget visible immediately (refer to Window create flags on page 919 for a list of available parameter values).
ExFlags See FRAMEWIN create flags on page 1214.
Id Window ID of the FRAMEWIN widget.
pTitle Title displayed in the title bar.
cb Optional pointer to a custom callback function for the client window.

Return value
Handle of the created FRAMEWIN widget; 0 if the function fails.

Additional information
The user callback routine is typically used for 2 purposes:
• to paint the client window (if filling with a color is not desired)
• to react to messages of child windows, typically dialog elements The normal behaviour of the client window is to paint itself, filling the entire window with the client color.
If the user callback also fills the client window (or a part of it), it can be desirable to set the client color to GUI_INVALID_COLOR, causing the window callback not to fill the client window.
The user callback of the client window does not receive all messages sent to the client window; some system messages are completely handled by the window callback routine and are not passed to the user callback. All notification messages as well as WM_PAINT and all user messages are sent to the user callback routine. The handle received by the user callback is the handle of the frame window (the parent window of the client window), except for the WM_PAINT message, which receives the handle of the client window.

FRAMEWIN_CreateIndirect()

6.2.9.4.1.9
Description
The prototype of this function is explained at the beginning of this chapter. Details can be found in the description of the function _CreateIndirect() on page 933. The element Para of the according GUI_WIDGET_CREATE_INFO structure is not used. The element
Flags is used according to the parameter ExFlags of the function FRAMEWIN_CreateEx().

FRAMEWIN_CreateUser()

6.2.9.4.1.10
Description
Prototype explained at the beginning of the chapter as _CreateUser() on
page 934. For a detailed description of the parameters the function FRAMEWIN_CreateEx() can be referred to.

FRAMEWIN_GetActive()

6.2.9.4.1.11
Description
Returns if the given FRAMEWIN widget is in active state or not.

Prototype
int FRAMEWIN_GetActive(FRAMEWIN_Handle hObj);

Parameters
Parameter Description
hObj Handle of FRAMEWIN widget.

Return value
1 if FRAMEWIN widget is in active state
0 if not.

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up