継承図

協調図

解説

■ 仕様と使い方

SFYLabelControl は、 各種ラベルコントロールを実装するための起点となります。

SFYLabelControl は、 フォーカス枠の描画機能と操作キーの管理を実装し、 いくつかの仮想関数のデフォルトの動作も実装します。

操作キーは、SFYLabelControl::SetOperateKey 関数を使用して設定します。 デフォルトでは、セレクトキーが操作キーとして割り当てられています。

SFYLabelControl::DrawFocus 関数の実装では、 ラベルコントロールの枠が状態に応じて以下のように描画されます。

図 312. ラベルコントロールの拡大図[フォーカス状態]

フォーカス状態では、 図にあるように領域の境界（外枠）とその内側（内枠）に枠線が２本それぞれ１ピクセルの幅で描画されます。

テキストや画像は内枠で囲まれるコンテンツ領域に描画されます。

内枠は、SFYLabelControl::SetFocusColor 関数で設定された色で描画されます。

外枠は、内枠の色の明度を基準にして計算された色で描画されます。 具体的には、内枠の色の明度が 0x7F より大きい場合はその色の RGB 値からそれぞれ 0x22 を減算した色、 0x7F 以下の場合はその色の RGB 値にそれぞれ 0x22 を加算した色で外枠は描画されます。

色の明度とは、SFXRGBColor::GetBrightness 関数によって得られる値です。

図 313. ラベルコントロールの拡大図[フォーカス以外の状態]

フォーカス以外の状態では、外枠も内枠も描画されません。

	背景の描画
	ラベルコントロールでは、SFYResponder::SetPropertyTransparent 関数を使用して設定する透過属性がデフォルトで true なので、 背景は SFYWidget::SetBackgroundColor 関数で設定した色で描画されません。

■ イベントとハンドラ

SFYLabelControl を継承するレスポンダでは、 SFYLabelControl::SFYLabelControl / SFYControl::SFYControl / SFYWidget::SFYWidget コンストラクタで登録されたハンドラの処理により、 下記のイベントを受信すると、対応する下記の仮想関数（ハンドラ）が最初に呼び出されます。 その後、開発者がレスポンダに登録したハンドラが呼び出されることになります。

	注意
	ハンドラの詳細については、 SFYLabelControl::SFYLabelControl / SFYControl::SFYControl / SFYWidget::SFYWidget コンストラクタの解説を参照してください。

	Tip
	ハンドラを登録する手間を省略できるので、 通常、これらのイベント処理は仮想関数をオーバーライドして記述します。

※デフォルトの動作にある "−" は何も実装していないことを表す。

	注釈
	※1. SFYResponder::InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, GetCurrentValue()), false) を実行します。 ※2. SFYResponder::SetVirtualBound(SFXRectangle(SFXGrid::ZeroInstance(), GetRealBound().GetSize())) を実行します。つまり、仮想領域を実領域に一致させます。

ユーザー定義ラベルコントロールを作成するときに最低限必要なコードを示します。

SFMTYPEDEFRESPONDER(USRLabelControl)
class USRLabelControl : public SFYLabelControl {
    SFMSEALRESPONDER(USRLabelControl)
    SFMRESPONDERINSTANTIATEFOUR(USRLabelControl, SFYLabelControl, SFYControl, SFYWidget, SFYResponder)
public:

    // レスポンダのタイプを定義する
    // 小文字と記号のみからなるタイプは予約されているので使えない
    enum CodeEnum {
        CODE_TYPE = four_char_code('U', 'L', 'B', 'L')
    };
    SFMTYPEDEFTYPE(CodeEnum)

public:
    static USRLabelControlSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit USRLabelControl(Void) static_throws;
    virtual ~USRLabelControl(Void);

    // 親クラスで定義されている仮想関数のうち、実装が推奨される仮想関数
    virtual Void HandleBoundRequest(SFXRectanglePtr rectangle) const;
    virtual Void HandleBoundOptimize(SFXRectanglePtr rectangle) const;
    virtual Void HandleBoundVirtual(Void);
    virtual Void HandleRenderRequest(SFXGraphicsPtr graphics) const;
};

USRLabelControl::USRLabelControl(Void) static_throws
{
    if (static_try()) {

        // レスポンダのタイプを設定する
        SetType(CODE_TYPE);

        // ラベルコントロールは背景を持たないので透過モードに設定する
        SetPropertyTransparent(true);

        // 初期化処理を記述する
    }
}

USRLabelControl::~USRLabelControl(Void)
{
    // 終了処理を記述する
}

USRLabelControlSmp USRLabelControl::NewInstance(SFCErrorPtr exception)
{
    return static_pointer_cast<USRLabelControl>(Factory(::new USRLabelControl, exception));
}

Void USRLabelControl::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    // SFYLabelControl::DrawFocus 関数を利用するので、フォーカス枠の大きさ分だけ縮小する
    rectangle->Deflate(GetFocusMargin());

    // フォーカス枠内部に最適な大きさを計算して rectangle パラメータに設定する
    // この関数内では、rectangle の原点は変更せず、rectangle のサイズだけを設定する(推奨)

    // SFYLabelControl::DrawFocus 関数を利用するので、フォーカス枠の大きさ分だけ拡大する
    rectangle->Inflate(GetFocusMargin());
    return;
}

Void USRLabelControl::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    // SFYLabelControl::DrawFocus 関数を利用するので、フォーカス枠の大きさ分だけ縮小する
    rectangle->Deflate(GetFocusMargin());

    // フォーカス枠内部に最適な大きさを rectangle パラメータ内の大きさに
    // 収まるように計算し、rectangle パラメータに設定する
    // この関数内では、rectangle の原点は変更せず、rectangle のサイズだけを設定する(推奨)

    // SFYLabelControl::DrawFocus 関数を利用するので、フォーカス枠の大きさ分だけ拡大する
    rectangle->Inflate(GetFocusMargin());
    return;
}

Void USRLabelControl::HandleBoundVirtual(Void)
{
    // 仮想領域が変更された場合に再計算が必要なものがあれば、ここに記述する
    return;
}

Void USRLabelControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // SFYLabelControl::DrawFocus 関数を使用してフォーカス枠を描画する
    DrawFocus(graphics, GetLocalBound());

    // フォーカス枠内部を描画する
    return;
}

参照

SFYLabelControl::SFYLabelControl | SFYControl::SFYControl | SFYWidget::SFYWidget | SFZSingleTextLabelControl | SFZSingleEditLabelControl | SFZMultipleTextLabelControl | SFZMultipleEditLabelControl | SFZImageLabelControl | 状態 | キーイベント[SFEVT_KEY] | 領域イベント[SFEVT_RESPONDER_BOUND] | 描画イベント[SFEVT_RESPONDER_RENDER] | ラベルコントロールを表す抽象クラス[SFYLabelControl]

メンバ

解説

このコンストラクタは、以下の初期化処理を行います。

	注意
	SFYLabelControl クラスを継承するレスポンダでは、 上記イベントが発生すると、それに対応するハンドラが呼び出されます。

内部実装

このコンストラクタの内部実装は以下の通りです。

/*protected */SFYLabelControl::SFYLabelControl(Void) static_throws
{
    static SFXRGBColor::AtomRecConst            rgb[] = {
        {{{0x00, 0xAA, 0xAA, 0xAA}}}
    };
    static SFXEventRange::AtomRecConst          trange[] = {
        #if TARGET_VERSION_GE(3, 0, 0)
        {       SFEVT_KEY_PRESS,      SFEVT_KEY_RELEASE,          SFP16_BEGIN,            SFP16_END},
        #else
        {       SFEVT_KEY_PRESS,         SFEVT_KEY_HELD,          SFP16_BEGIN,            SFP16_END},
        #endif
        {             SFEVT_KEY,              SFEVT_KEY,          SFP16_BEGIN,            SFP16_END}
    };
    SFYHandler::RuleRec                         trule[lengthof(trange)];

    if (static_try()) {
        SetType(CODE_TYPE);
        trule[0].spp = XANDLER_FUNCTION(OnShield);
        trule[0].reference = this;
        trule[1].spp = XANDLER_FUNCTION(OnKey);
        trule[1].reference = this;
        static_throw(RegisterHandler(atomic_cast(trange), trule, lengthof(trange)));
        if (static_try()) {
            _color.focus.Set(rgb[0]);
            _key.operate = AVK_SELECT;
        }
    }
}// SFYLabelControl::SFYLabelControl //

/*private */XANDLER_IMPLEMENT_BOOLEVENT(SFYLabelControl, OnShield, invoker, event)
{
    unused(invoker);
    return (event.GetP16() == _key.operate);
}// XANDLER_IMPLEMENT_BOOLEVENT(SFYLabelControl, OnShield) //

/*private */XANDLER_IMPLEMENT_BOOLEVENT(SFYLabelControl, OnKey, invoker, event)
{
    Bool                                        result(false);

    unused(invoker);
    if (event.GetP16() == _key.operate) {
        HandleOperateKey();
        result = true;
    }
    return result;
}// XANDLER_IMPLEMENT_BOOLEVENT(SFYLabelControl, OnKey) //

参照

SFYResponder::SetType | SFYLabelControl::CodeEnum | SFYLabelControl::SetFocusColor | SFYLabelControl::HandleOperateKey | SFXEvent | SFXRGBColor | タイプ | イベント | キーイベント[SFEVT_KEY]

解説

このデストラクタは、何も行いません。

内部実装

このデストラクタの内部実装は以下の通りです。

/*protected virtual */SFYLabelControl::~SFYLabelControl(Void)
{
}// SFYLabelControl::~SFYLabelControl //

解説

この関数は、 フォーカス状態にあるとき、 以下のラベルコントロールの枠を描画します。

独自の処理を行う場合は、この関数をオーバーライドします。

	Tip
	この関数は、SFYLabelControl クラスを継承する具象クラスの HandleRender 関数内で呼び出されます。

図 314. ラベルコントロールの拡大図[フォーカス状態]

フォーカス状態では、 図にあるように領域の境界（外枠）とその内側（内枠）に枠線が２本それぞれ１ピクセルの幅で描画されます。

テキストや画像は内枠で囲まれるコンテンツ領域に描画されます。

内枠は、SFYLabelControl::SetFocusColor 関数で設定された色で描画されます。

外枠は、内枠の色の明度を基準にして計算された色で描画されます。 具体的には、内枠の色の明度が 0x7F より大きい場合はその色の RGB 値からそれぞれ 0x22 を減算した色、 0x7F 以下の場合はその色の RGB 値にそれぞれ 0x22 を加算した色で外枠は描画されます。

色の明度とは、SFXRGBColor::GetBrightness 関数によって得られる値です。

図 315. ラベルコントロールの拡大図[フォーカス以外の状態]

フォーカス以外の状態では、外枠も内枠も描画されません。

内部実装

この関数の内部実装は以下の通りです。

/*protected */Void SFYLabelControl::DrawFocus(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle) const
{
    SFXRectangle                                lx;
    SFXRGBColor                                 rgb;

    if (GetStateFocus(true)) {
        lx.Set(rectangle);
        rgb.Set(_color.focus);
        if (GetStateActive(true)) {
            (rgb.GetBrightness() > 0x7F) ? rgb.SubRGB(0x22) : rgb.AddRGB(0x22);
        }
        graphics->DrawRectangle(lx, rgb);
        lx.Deflate(1, 1);
        graphics->DrawRectangle(lx, _color.focus);
    }
    return;
}// SFYLabelControl::DrawFocus //

参照

SFYLabelControl::GetFocusMargin | SFYLabelControl::SetFocusColor | SFXRGBColor

戻り値

フォーカス状態にあるときのラベルコントロールの枠を描画する色。

解説

この関数は、フォーカス状態にあるときのラベルコントロールの枠を描画する色を取得します。

参照

SFYLabelControl::SetFocusColor | SFYLabelControl::DrawFocus | SFXRGBColor

戻り値

フォーカス状態にあるときに描画されるラベルコントロールのマージン[SFXMargin(2, 2, 2, 2)]。

解説

この関数は、フォーカス状態にあるときに描画されるラベルコントロールの境界とラベルテキスト間のマージンを取得します。

ラベルコントロールのマージンとは、 テキストや画像を描画するためのコンテンツ領域を囲む幅２ピクセルのラベルコントロールの枠領域のことです。 ローカル領域の左端、上端、右端、下端からそれぞれ２ピクセルの余白領域[SFXMargin(2, 2, 2, 2)]です。

詳しくは、SFYLabelControl::DrawFocus を参照してください。

参照

SFXMargin | SFYLabelControl::DrawFocus | SFYLabelControl::SetFocusColor | ローカル領域

戻り値

ラベルの操作キー。

解説

この関数は、ラベルの操作キーを取得します。

参照

SFYLabelControl::SetOperateKey | AVKType

解説

この関数は、SFYLabelControl::SetOperateKey 関数で設定した操作キーの SFEVT_KEY イベント （キーイベント[SFEVT_KEY]）を受信したときに呼び出されます。

独自のキーイベント処理を行いたい場合は、この関数をオーバーライドします。

デフォルトの実装では、 自分自身に結果イベント [SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, SFYControl::GetCurrentValue())] を送信します。

内部実装

この関数の内部実装は以下の通りです。

/*protected virtual */Void SFYLabelControl::HandleOperateKey(Void)
{
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, GetCurrentValue()), false);
    return;
}// SFYLabelControl::HandleOperateKey //

参照

SFYLabelControl::SetOperateKey | SFXEvent | SFYControl::GetCurrentValue | キーイベント[SFEVT_KEY] | 結果イベント [SFEVT_RESPONDER_RESULT]

解説

この関数は、 フォーカス状態にあるときのラベルコントロールの内枠の色を設定します。

外枠の色は、内枠の色の明度を基準にして計算された色になります。

デフォルト値: SFXRGBColor(0xAA, 0xAA, 0xAA, 0x00)[灰色]

詳しくは、SFYLabelControl::DrawFocus を参照してください。

参照

SFYLabelControl::GetFocusColor | SFYLabelControl::DrawFocus | SFXRGBColor::GetBrightness | SFXRGBColor | 状態

解説

この関数は、ラベルコントロールの操作キーを設定します。

デフォルト値: AVK_SELECT

参照

SFYLabelControl::GetOperateKey | AVKType

参照

SFYResponder::GetType | SFYResponder::SetType