Inheritance diagram

Collaboration diagram

Description

How to use

SFZQuestionDialog is the dialog to display a selection message, which consists of the icon image, the message text, the ANOTHER button, the OK button, and the CANCEL button.

Each element can be omitted(it will be omitted if nothing is set with the Set function.

Figure 360. Example: The bahaviour of SFZQuestionDialog

The icon image, the message text, and the ANOTHER, OK, and CANCEL buttons are internally contained as the SFZImageLabelControl, SFZMultipleTextLabelControl, and SFZTextButtonControl instance respectively. There are the APIs to get these instances.

Since the states of the icon image and the message text are set to "disable", the focus cannot be moved to these objects. The ANOTHER, OK, and CANCEL buttons, whose states are set to "enable", can be focused with the scroll keys set using the SFYContainer::SetScrollUpKey and SFYContainer::SetScrollDownKey functions. When the dialog is first displayed on the device screen, the button set last using the SFZQuestionDialog::SetButtonText function is focused.

If the icon image, the message text, or the button text is not set with the SFZQuestionDialog::SetIconImage, SFZQuestionDialog::SetMessageText, or SFZQuestionDialog::SetButtonText function respectively, it will not be displayed since regarded as omitted.

In the default implementation, the selection message dialog[SFZQuestionDialog] will receive the following result events[SFEVT_RESPONDER_RESULT].

The handler for these events can be registered. The default handler closes the dialog only.

The operation key of the dialog is set with the SFZDialog::SetOperateKey function. The operation key of the button for operating the ANOTHER, CANCEL, and OK buttons is set with the SFYButtonControl::SetOperateKey function. By default, the operation key of the dialog and the operation key of the button are set to the SELECT key. When the button is displayed, the SELECT key is handled as the operation key of the button.

The ESCAPE key is set with the SFZDialog::SetEscapeKey function. By default, the ESCAPE key is set to the CLEAR key.

	Note
	The timer processing callback scheduled with the SFZDialog::ScheduleTimer function will be canceled automatically when the operation key of the dialog, the ESCAPE key, the OK button, the CANCEL button or the ANOTHER button is pressed.

Operating a dialog with its operation key

If all buttons are omitted or their states are set to "disable", dialog will be operated by its operation key. In the default implementation, its behaviour is the same as when the OK button is pressed. That is, if the operation key is pressed, the (SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK) event will be sent, and then the dialog will close. This function is used for the dialog with no button which has only the warning message and is closed with its operation key.

	Default background color
	In SFZQuestionDialog, the default background color set with the SFYWidget::SetBackgroundColor function is the gray color[SFXRGBColor(0xEE, 0xEE, 0xEE,0x00)].

	IMPORTANT
	In the concrete container, the SFYResponder::SetParent, SFYResponder::SetState, and SFYResponder::SetRealBound functions must be always called. Other functions are optionally called.

Sample code

SFMTYPEDEFCLASS(USRApplication)
class USRApplication: public SFYApplication {
  SFMSEALCOPY(USRApplication)
public:
  static SFCInvokerPtr Factory(Void);
private:
  explicit USRApplication(Void) static_throws; 
  virtual ~USRApplication(Void);

  // result handler
  XANDLER_DECLARE_VOIDRESULT(OnResult)
};

USRApplication::USRApplication(Void) static_throws
{
  // ... (omitted) ...

  SFZQuestionDialogSmp dialog;  // smart pointer of SFZQuestionDialog
  SFCError error(SFERR_NO_ERROR);

  // create the dialog
  if ((dialog = SFZQuestionDialog::NewInstance(&error)) != null) {

    // set the dialog's parent responder to USRApplication
    error = dialog->SetParent(GetThis());
    if (error == SFERR_NO_ERROR) {

      // register the result handler into the dialog
      error = dialog->RegisterHandler(
        SFXEventRange(SFEVT_RESPONDER_RESULT, SFEVT_RESPONDER_RESULT, SFP16_BEGIN, SFP16_END),
        XANDLER_INTERNAL(OnResult)
      );
      if (error == SFERR_NO_ERROR) {

        // set the image for the dialog's icon
        // * image can be set from the resource file
        error = dialog->SetIconImage(SFXPath("resource.bar"), IMAGE_ID);
        if (error == SFERR_NO_ERROR) {

          // set the text for the dialog's message
          // * SFXWideString text can be set from the resource file
          error = dialog->SetMessageText("hello world\n\nThis is a question message.");
          if (error == SFERR_NO_ERROR) {

            // set the text for the dialog's ANOTHER button
            // * SFXWideString text can be set from the resource file
            error = dialog->SetButtonText(SFZQuestionDialog::BUTTON_ANOTHER, "ANOTHER");
            if (error == SFERR_NO_ERROR) {

              // set the text for the dialog's CANCEL button
              // * SFXWideString text can be set from the resource file
              error = dialog->SetButtonText(SFZQuestionDialog::BUTTON_CANCEL, "CANCEL");
              if (error == SFERR_NO_ERROR) {

                // set the text for the dialog's OK button
                // since the text of OK button is set last, first OK button is displayed in the focus state
                // * SFXWideString text can be set from the resource file
                error = dialog->SetButtonText(SFZQuestionDialog::BUTTON_OK, "OK");
                if (error == SFERR_NO_ERROR) {

                  // Calculate the suitable dialog region within the hint region obtained by deflating the screen device region by (20, 20) margin, 
                  // which will be aligned at the center and the middle of the hint region.
                  // Set the dialog's real region to it.
                  dialog->SetRealBound(dialog->GetSuitableBound(GetLocalBound().Deflate(20, 20), SFYResponder::HORIZONTAL_CENTER, SFYResponder::VERTICAL_MIDDLE));

                  // set the dialog's state to "visible" + "active" + "enable" + "focus" together
                  dialog->SetState(true, true, true, true);

                  // move the dialog foremost
                  dialog->ToFront();
                }
              }
            }
          }
        }
      }
    }
  }
  static_throw(error);
}

// result handler
XANDLER_IMPLEMENT_VOIDRESULT(USRApplication, OnResult, invoker, reason, result)
{
    // the dialog will be passed via the invoker argument
    // the P16 value of the result event will be passed via the reason argument
    // "0" will be passed via the result argument

    switch (reason) {
        case SFP16_RESULT_OK:

            // when the OK button or the operation key is pressed

            ...

            break;

        case SFP16_RESULT_CANCEL:

            // when the CANCEL button is pressed

            ...

            break;
        case SFP16_RESULT_ANOTHER:

            // when the OTHER button is pressed

            ...

            break;
        case SFP16_RESULT_ESCAPE:

            // when the ESCAPE key is pressed or the time scheduled with ScheduleTimer() elapses

            ...

            break;
    }

    // close the dialog
    invoker->Terminate();

    return;
}

Figure 361. Execution result of the above sample code [SFZQuestionDialog]

Sample code of this dialog with a title and a border

A frame with a border and/or a title can be attached to this dialog.

The below is the code to attach a bevel frame with a title [SFZTitleBevelFrame] to this dialog.

// define the class
SFMTYPEDEFCLASS(USRApplication)
class USRApplication : public SFYApplication {
  SFMSEALCOPY(USRApplication)
public:
  static SFCInvokerPtr Factory(Void);
private:
  explicit USRApplication(Void) static_throws;
  virtual ~USRApplication(Void);

  XANDLER_DECLARE_VOIDRESULT(OnResult)        // dialog's result handler
};


// constructor
USRApplication::USRApplication(Void) static_throws
{
  // ... (omitted) ...

  SFZTitleBevelFrameSmp frame;  // smart pointer to SFZTitleBevelFrame
  SFZQuestionDialogSmp  dialog; // smart pointer to SFZQuestionDialog
  SFCError              error(SFERR_NO_ERROR);

  // create the frame
  if ((frame = SFZTitleBevelFrame::NewInstance(&error)) != null) {

    // set frame title
    frame->SetText("SFXQuestionDialog");

    // In general, the frame's state is set to "visible" + "active" + "enable" + "focus".
    frame->SetState(true, true, true, true);

    // create and place dialog
    if ((dialog = SFZQuestionDialog::NewInstance(&error)) != null) {

      // set dialog's parent responder to the application class(root)
      error = dialog->SetParent(GetThis());
      if (error == SFERR_NO_ERROR) {

        // set dialog's frame
        error = dialog->SetFrame(frame);
        if (error == SFERR_NO_ERROR) {

          // register the result handler into the dialog
          error = dialog->RegisterHandler(
               SFXEventRange(SFEVT_RESPONDER_RESULT, SFEVT_RESPONDER_RESULT, SFP16_BEGIN, SFP16_END),
                      XANDLER_INTERNAL(OnResult)
          );
          if (error == SFERR_NO_ERROR) {

            // set the image for the dialog's icon
            // * SFBImage image can be set from the resource file or normal file
            error = dialog->SetIconImage(SFXPath(USRApplication_RES_FILE), ICON);
            if (error == SFERR_NO_ERROR) {

              // set the text for the dialog's message
              // * SFXWideString text can be set from the resource file
              error = dialog->SetMessageText("This is a question dialog with a title bevel frame.");
              if (error == SFERR_NO_ERROR) {

                // set the text for the dialog's ANOTHER button
                // * SFXWideString text can be set from the resource file
                error = dialog->SetButtonText(SFZQuestionDialog::BUTTON_ANOTHER, "ANOTHER");
                if (error == SFERR_NO_ERROR) {

                  // set the text for the dialog's CANCEL button
                  // * SFXWideString text can be set from the resource file
                  error = dialog->SetButtonText(SFZQuestionDialog::BUTTON_CANCEL, "CANCEL");
                  if (error == SFERR_NO_ERROR) {

                    // set the text to the dialog's OK button
                    // OK button is focused since the text for this button is set last
                    // * SFXWideString text can be set from the resource file
                    error = dialog->SetButtonText(SFZQuestionDialog::BUTTON_OK, "OK");
                    if (error == SFERR_NO_ERROR) {

                      // Calculate the suitable dialog region within the hint region obtained by deflating the screen device region by (20, 20) margin, 
                      // which will be aligned at the center and the middle of the hint region.
                      // Set the dialog's real region to it.
                      // * Automatically, the frame's real region will be set to the region obtained by inflating it by the frame margin.
                      dialog->SetRealBound(dialog->GetSuitableBound(GetLocalBound().Deflate(20, 20), SFYResponder::HORIZONTAL_CENTER, SFYResponder::VERTICAL_MIDDLE));

                      // move the dialog foremost
                      // * automatically, the frame will be moved foremost together
                      dialog->SetState(true, true, true, true);

                      // move the dialog foremost
                      dialog->ToFront();
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  static_throw(error);
}


// result handler
XANDLER_IMPLEMENT_VOIDRESULT(USRApplication, OnResult, invoker, reason, result)
{
  // the dialog will be passed via the invoker argument
  // the P16 value of the result event will be passed via the reason argument
  // "0" will be passed via the result argument

  switch (reason) {

    case SFP16_RESULT_OK:

      // when the OK button or the operation key is pressed

      ...

      break;

    case SFP16_RESULT_CANCEL:

      // when the CANCEL button is pressed

      ...

     break;

    case SFP16_RESULT_ANOTHER:

      // when the ANOTHER button is pressed

      ...

      break;

    case SFP16_RESULT_ESCAPE:

      // when the ESCAPE key is pressed or the time scheduled with ScheduleTimer() elapses

      ...

      break;
  }

  // close the dialog only
  // * automatically, the frame will be detached from the dialog and become invisible
  invoker->Terminate();

  return;
}

Figure 362. Execution result of the above code [SFZQuestionDialog and SFZTitleBevelFrame]

Note when calling and passing nothing as an argument to GetSuitableBound()

Before calling and passing nothing as an argument to the GetSuitableBound() function, the real region( local region*) must be set using the SFYResponder::SetRealBound function. The width of this real region is used as the hint value to calculate the size of its suitable region. In general, the value more than [the width of the used font + (the width of the frame margin) * 2] should be set. * Unless the virtual region is set, the real region is the same with the virtual region. When setting the real region which is used for the hint value, you have to consider the frame margin set with the SFZMessageDialog::SetFrameSize function. Reference: Getting the Suitable Size of Responder for Displaying a Multiple Text |

Reference

Dialog to Display a Selection Message [SFZQuestionDialog] | SFZDialog | SFZMessageDialog | SFZImageLabelControl | SFZMultipleTextLabelControl | SFZTextButtonControl | SFYWidget | SFXRGBColor | SFYWidget::SetBackgroundColor | SFZQuestionDialog::SetIconImage | SFZQuestionDialog::SetMessageText | SFZQuestionDialog::SetButtonText | SFZDialog::SetOperateKey | SFZDialog::SetEscapeKey | SFYButtonControl::SetOperateKey | SFYContainer::SetScrollUpKey | SFYContainer::SetScrollDownKey | SFZDialog::ScheduleTimer | SFYResponder::ToFront | SFYResponder::Terminate | Frame | SFZTitleBevelFrame | Real Region | Local Region | Virtual Region | Getting the Suitable Size of Responder for Displaying a Multiple Text | SFZMessageDialog::SetFrameSize

Member

Description

This constructor performs the initializations as follows:

Reference

SFYResponder::SetType | SFZQuestionDialog::CodeEnum | SFZQuestionDialog::DefaultEnum | SFZMultipleTextLabelControl::HorizontalEnum | SFZMultipleTextLabelControl::VerticalEnum | SFZMultipleTextLabelControl | SFXEvent | SFXRGBColor | Type | Event | Result Event[SFEVT_RESPONDER_RESULT]

Description

This destructor does nothing.

Return value

Text button control(SFZTextButtonControl) which the SFZQuestionDialog class contains as the ANOTHER, CANCEL, or OK button internally.

Description

This function gets the instance of the SFZTextButtonControl class which the SFZQuestionDialog class contains as the OK button internally.

The text or color of the button can be changed using the functions of the SFZTextButtonControl class.

Reference

SFZQuestionDialog::SetButtonText | SFZTextButtonControl | SFZQuestionDialog::ButtonEnum

Description

This function gets the text of the button which is specified in the "button" argument.

Reference

SFZQuestionDialog::SetButtonText | SFZQuestionDialog::ButtonEnum | SFXWideString

Reference

SFZQuestionDialog::SetFrameSize

Description

This function gets the instance of the SFZImageLabelControl class which SFZQuestionDialog contains as an icon image of this dialog internally.

The image or alignment of the icon can be changed using the APIs of the SFZImageLabelControl class.

Reference

SFZQuestionDialog::SetIconImage | SFZImageLabelControl

Reference

SFZQuestionDialog::SetIconImage | SFBImage | BREW API IImage

Description

This function gets the instance of the SFZMultipleTextLabelControl class which SFZQuestionDialog contains as a message text of this dialog internally.

The color or alignment of the message text can be changed using the APIs of the SFZMultipleTextLabelControl class.

Reference

SFZQuestionDialog::SetMessageText | SFZMultipleTextLabelControl

Reference

SFZQuestionDialog::SetMessageText | SFXWideString

Reference

SFZQuestionDialog::SetSpaceSize

Description

This function will be called when the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE, rectangle)] is received.

This function calculates the suitable rectangle size of this dialog within the hint rectangle specified as an argument.

	Region event[(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE) event]
	If the rectangle argument of the hint region is specified, the SFYResponder::GetSuitableBound function will send the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE, rectangle)] to this responder. Then, the SFYWidget::HandleBoundOptimize virtual function will be called. The rectangle element (P32 parameter) of the region event is set to the hint region as an initial value.

Internal Implementation

Internal implementation of the SFZQuestionDialog::HandleBoundOptimize function is as follows:

/*protected virtual */Void SFZQuestionDialog::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    SFXRectangle                                rx;
    SFXSize                                     icon;
    SFXSize                                     message;
    SFXSize                                     button[BUTTON_LIMIT];
    SInt32                                      r0;
    SInt16                                      horizontal;
    SInt16                                      vertical;

    rectangle->Deflate(_frame, _frame);
    rx.Set(*rectangle);
    icon.Set(SFXSize::ZeroInstance());
    message.Set(SFXSize::ZeroInstance());
    for (r0 = 0; r0 < BUTTON_LIMIT; ++r0) {
        button[r0].Set(SFXSize::ZeroInstance());
    }
    horizontal = 0;
    vertical = 0;
    for (r0 = BUTTON_LIMIT - 1; r0 >= 0; --r0) {
        if (_button[r0]->GetStateVisible()) {
            button[r0].Set(_button[r0]->GetSuitableBound(rx).GetSize());
            if (!button[r0].IsEmpty()) {
                rx.SubBottom(button[r0].GetHeight() + _space);
                ++vertical;
            }
        }
    }
    if (_icon->GetStateVisible()) {
        icon.Set(_icon->GetSuitableBound(rx).GetSize());
        if (!icon.IsEmpty()) {
            rx.AddLeft(icon.GetWidth() + _space);
            ++horizontal;
            if (message.IsEmpty()) {
                ++vertical;
            }
        }
    }
    if (_message->GetStateVisible()) {
        message.Set(_message->GetSuitableBound(rx).GetSize());
        if (!message.IsEmpty()) {
            ++horizontal;
            if (icon.IsEmpty()) {
                ++vertical;
            }
        }
    }
    rx.SetSize(icon.GetWidth() + message.GetWidth(), (icon.GetHeight() > message.GetHeight()) ? (icon.GetHeight()) : (message.GetHeight()));
    if (--horizontal > 0) {
        rx.AddWidth(_space * horizontal);
    }
    if (--vertical > 0) {
        rx.AddHeight(_space * vertical);
    }
    for (r0 = 0; r0 < BUTTON_LIMIT; ++r0) {
        rx.SetWidth((rx.GetWidth() > button[r0].GetWidth()) ? (rx.GetWidth()) : (button[r0].GetWidth()));
        rx.AddHeight(button[r0].GetHeight());
    }
    rectangle->SetSize(rx.GetSize());
    rectangle->Inflate(_frame, _frame);
    return;
}// SFZQuestionDialog::HandleBoundOptimize //

Reference

SFYResponder::GetSuitableBound | | SFXEvent | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND] SFZTextButtonControl::HandleBoundOptimize | SFZMultipleTextLabelControl::HandleBoundOptimize | SFZImageLabelControl::HandleBoundOptimize | SFZQuestionDialog::SetFrameSize | SFZQuestionDialog::SetSpaceSize

Description

This function will be called when the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event is received.

This function will equalize the virtual region with the real region when the real region is changed.

	Sending the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event
	The (SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event will occur when the real region is changed by calling the SFYResponder::SetRealBound function.

Processing when the real region is changed

Other than overriding this virtual function, there is another method to define and implement the handler for the region event[XANDLER_DECLARE_VOIDBOUND], and register it into the responder. In the processing when the real region is updated, this virtual function is executed first, and next the handlers for the region event are executed in the registered order. In almost all cases, the method to override this virtual function is adopted since defining, implementing and registering the handler for the region event can be omitted.

Internal Implementation

Internal implementation of the SFZQuestionDialog::HandleBoundReal function is as follows:

/*protected virtual */Void SFZQuestionDialog::HandleBoundReal(Void)
{
    SetVirtualBound(SFXRectangle(SFXGrid::ZeroInstance(), GetRealBound().GetSize()));
    return;
}// SFZQuestionDialog::HandleBoundReal //

Reference

SFYResponder::SetRealBound | Real Region | Virtual Region | Region Event[SFEVT_RESPONDER_BOUND] | Handler for Region Event[XANDLER_DECLARE_VOIDBOUND]

Description

This function will be called when the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST, rectangle)] is received.

This function calculates the suitable rectangle size of this dialog.

Region event[(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST) event]

If the rectangle argument of the hint region is not specified, the SFYResponder::GetSuitableBound function will send the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST, rectangle)] to this responder. Then, the SFYWidget::HandleBoundRequest virtual function will be called. The rectangle element (P32 parameter) of the region event is set to the real region as an initial value. Tip Default value of the real region: SFXRectangle(0, 0, 0, 0)

Internal Implementation

Internal implementation of the SFZQuestionDialog::HandleBoundRequest function is as follows:

/*protected virtual */Void SFZQuestionDialog::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    SFXRectangle                                rx;
    SFXRectangle                                lx;
    SFXSize                                     icon;
    SFXSize                                     message;
    SFXSize                                     button[BUTTON_LIMIT];
    SInt32                                      r0;
    SInt16                                      horizontal;
    SInt16                                      vertical;

    rectangle->Deflate(_frame, _frame);
    rx.Set(*rectangle);
    icon.Set(SFXSize::ZeroInstance());
    message.Set(SFXSize::ZeroInstance());
    for (r0 = 0; r0 < BUTTON_LIMIT; ++r0) {
        button[r0].Set(SFXSize::ZeroInstance());
    }
    horizontal = 0;
    vertical = 0;
    for (r0 = BUTTON_LIMIT - 1; r0 >= 0; --r0) {
        if (_button[r0]->GetStateVisible()) {
            button[r0].Set(_button[r0]->GetSuitableBound().GetSize());
            if (!button[r0].IsEmpty()) {
                rx.SetWidth((rx.GetWidth() > button[r0].GetWidth()) ? (rx.GetWidth()) : (button[r0].GetWidth()));
                rx.SubBottom(button[r0].GetHeight() + _space);
                ++vertical;
            }
        }
    }
    if (_icon->GetStateVisible()) {
        icon.Set(_icon->GetSuitableBound().GetSize());
        if (!icon.IsEmpty()) {
            rx.AddLeft(icon.GetWidth() + _space);
            rx.SetHeight((rx.GetHeight() > icon.GetHeight()) ? (rx.GetHeight()) : (icon.GetHeight()));
            ++horizontal;
            if (message.IsEmpty()) {
                ++vertical;
            }
        }
    }
    if (_message->GetStateVisible()) {
        lx.Set(_message->GetRealBound());
        _message->SetRealBound(rx);
        message.Set(_message->GetSuitableBound().GetSize());
        _message->SetRealBound(lx);
        if (!message.IsEmpty()) {
            ++horizontal;
            if (icon.IsEmpty()) {
                ++vertical;
            }
        }
    }
    rx.SetSize(icon.GetWidth() + message.GetWidth(), (icon.GetHeight() > message.GetHeight()) ? (icon.GetHeight()) : (message.GetHeight()));
    if (--horizontal > 0) {
        rx.AddWidth(_space * horizontal);
    }
    if (--vertical > 0) {
        rx.AddHeight(_space * vertical);
    }
    for (r0 = 0; r0 < BUTTON_LIMIT; ++r0) {
        rx.SetWidth((rx.GetWidth() > button[r0].GetWidth()) ? (rx.GetWidth()) : (button[r0].GetWidth()));
        rx.AddHeight(button[r0].GetHeight());
    }
    rectangle->SetSize(rx.GetSize());
    rectangle->Inflate(_frame, _frame);
    return;
}// SFZQuestionDialog::HandleBoundRequest //

Reference

SFYResponder::GetSuitableBound | SFXEvent | Real Region Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND] SFZTextButtonControl::HandleBoundRequest | SFZMultipleTextLabelControl::HandleBoundRequest | SFZImageLabelControl::HandleBoundRequest | Real Region | Local Region | Virtual Region | Getting the Suitable Size of Responder for Displaying a Multiple Text | SFZQuestionDialog::SetFrameSize | SFZQuestionDialog::SetSpaceSize

Description

This function will be called when the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event is received.

This function will relocate the icon, the message, and the button within this dialog when the virtual region is changed.

	CAUTION
	If the icon, the message, the ANOTHER button, the OK button, or the CANCEL button is omitted, the corresponding item will not be relocated.

	Sending the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event
	The (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event will occur when the virtual region is changed by calling the SFYResponder::SetRealBound or SFYResponder::SetVirtualBound function.

Another method when the virtual region is changed

Other than overriding this virtual function, it is possible to define and implement the handler for region event[XANDLER_DECLARE_VOIDBOUND], and register it into the responder. In the processing when the virtual region is updated, this virtual function is executed first, and next the handlers for region event are executed in the registered order. In almost all cases, the method to override this virtual function is adopted since defining, implementing and registering the handler for region event can be omitted.

Internal Implementation

Internal implementation of the SFZQuestionDialog::HandleBoundVirtual function is as follows:

/*protected virtual */Void SFZQuestionDialog::HandleBoundVirtual(Void)
{
    Relocate();
    return;
}// SFZQuestionDialog::HandleBoundVirtual //

/*private */Void SFZQuestionDialog::Relocate(Void)
{
    SFXRectangle                                lx;
    SFXRectangle                                icon;
    SFXRectangle                                message;
    SFXRectangle                                button[BUTTON_LIMIT];
    SInt32                                      r0;

    lx.Set(GetLocalBound());
    lx.Deflate(_frame, _frame);
    icon.Set(SFXRectangle::ZeroInstance());
    message.Set(SFXRectangle::ZeroInstance());
    for (r0 = 0; r0 < BUTTON_LIMIT; ++r0) {
        button[r0].Set(SFXRectangle::ZeroInstance());
    }
    for (r0 = BUTTON_LIMIT - 1; r0 >= 0; --r0) {
        if (_button[r0]->GetStateVisible()) {
            button[r0].Set(_button[r0]->GetSuitableBound(lx));
            button[r0].SnapLeftBottom(lx.GetLeftBottom());
            if (!button[r0].IsEmpty()) {
                button[r0].SetRight(lx.GetRight());
                lx.SubBottom(button[r0].GetHeight() + _space);
            }
        }
    }
    if (_icon->GetStateVisible()) {
        icon.Set(_icon->GetSuitableBound(lx));
        icon.SnapLeftTop(lx.GetLeftTop());
        if (!icon.IsEmpty()) {
            lx.AddLeft(icon.GetWidth() + _space);
        }
    }
    if (_message->GetStateVisible()) {
        message.Set(_message->GetSuitableBound(lx));
        message.SnapRightTop(lx.GetRightTop());
        if (!message.IsEmpty()) {
            message.SetLeftBottom(lx.GetLeftBottom());
        }
    }
    _icon->SetRealBound(icon);
    _message->SetRealBound(message);
    for (r0 = 0; r0 < BUTTON_LIMIT; ++r0) {
        _button[r0]->SetRealBound(button[r0]);
    }
    return;
}// SFZQuestionDialog::Relocate //

Reference

SFYResponder::SetRealBound | SFYResponder::SetVirtualBound | Virtual Region | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND] | Virtual Region | Real Region | Local Region SFZTextButtonControl::HandleBoundRequest | SFZMultipleTextLabelControl::HandleBoundRequest | SFZImageLabelControl::HandleBoundRequest | SFZQuestionDialog::SetFrameSize | SFZQuestionDialog::SetSpaceSize

Argument

Return value

Description

This function creates a new instance of this responder class.

If succeeds, a not null pointer will be returned, and the "exception" argument is SFERR_NO_ERROR. If fails such as insufficient memory, a null pointer will be returned, and the "exception" argument holds the error value.

Example

The code to create a new instance of this responder class is as follows:

SFZQuestionDialogSmp _questiondialog;
SFCError error;

if ((_questiondialog = SFZQuestionDialog::NewInstance(&error)) != null) {

    ...
}

Description

This function sets the button text of this dialog to the specified value.

If the button text is not set using this function, the corresponding button will not be displayed on this dialog.

In addition, the text set with this function is internally contained by the instance of the SFZTextButtonControl class. This instance can be obtained by calling the SFZQuestionDialog::GetButton function.

Reference

SFZQuestionDialog::GetButtonText | SFZQuestionDialog::ButtonEnum | SFZQuestionDialog::GetButton | SFZTextButtonControl | SFXWideString

Description

This function sets the size of frame margin of this dialog to the specified value. [pixels]

Default: SFZQuestionDialog::DEFAULT_FRAME [5 pixels]

	Frame margin
	Frame margin is the margin between the border and the controls of this dialog. This margin has the same value from the top, bottom, left, and right edges of this dialog. The icon, the message, and the button are placed at the left-top, right-top, and bottom of this dialog with this frame margin respectively.

Figure 363. Frame margin[SFZQuestionDialog(Expanded Figure)]

The icon, the message, and the button of the dialog are placed in the region surrounded by the frame margin.

Reference

SFZQuestionDialog::GetFrameSize | SFZQuestionDialog::DefaultEnum

Description

This function sets the icon image of this dialog by specifying the image object directly or reading from the resource file.

The image of which size is in valid or the animated bitmap cannot be used.

If the icon image is not set using this function, the corresponding icon will not be displayed on this dialog.

In addition, the icon image set with this function is contained as the instance of SFZImageLabelControl class. This instance can be obtained by calling the SFZQuestionDialog::GetIcon function.

Reference

SFZQuestionDialog::GetIconImage | SFZQuestionDialog::GetIcon | SFZImageLabelControl | SFBImage | BREW API IImage

Description

This function sets the message text of this dialog by specifying the image object directly or reading from the resource file.

If the message text is not set using this function, the message will not be displayed on this dialog.

In addition, the icon image set with this function is contained as the instance of SFZMultipleTextLabelControl class. This instance can be obtained by calling the SFZQuestionDialog::GetMessage function.

Reference

SFZQuestionDialog::GetMessageText | SFZQuestionDialog::GetMessage | SFZMultipleTextLabelControl | SFXWideString

Description

This function sets the size of the space margin of this dialog to the specified value. [pixels]

When calculating the suitable size of this dialog automatically, the controls are placed with the space margin between them.

Default: SFZQuestionDialog::DEFAULT_SPACE [5 pixels]

	Space margin
	Space margin is the margin between the controls of this dialog. The space margin is set between the icon and the message, and between the message and the button. If the height of the dialog region is big, the space between the message and the button may be bigger than the space margin.

Figure 364. Space margin[SFZQuestionDialog(Expanded Figure)]

The space margin is set between the icon and the message, and between the message and the button.

If the height of the dialog region is big, the space between the message and the button may be bigger than the space margin.

Reference

SFZQuestionDialog::GetSpaceSize | SFZQuestionDialog::DefaultEnum

Reference

SFYResponder::GetType | SFYResponder::SetType

Description

	Frame margin
	Frame margin is the margin between the border and the controls of this dialog. This margin has the same value from the top, bottom, left, and right edges of this dialog. The icon, the message, and the button are placed at the left-top, right-top, and bottom of this dialog with this frame margin respectively.

Figure 365. Frame margin[SFZQuestionDialog(Expanded Figure)]

The icon, the message, and the button of the dialog are placed in the region surrounded by the frame margin.

	Space margin
	Space margin is the margin between the controls of this dialog. The space margin is set between the icon and the message, and between the message and the button. If the height of the dialog region is big, the space between the message and the button may be bigger than the space margin.

Figure 366. Space margin[SFZQuestionDialog(Expanded Figure)]

The space margin is set between the icon and the message, and between the message and the button.

If the height of the dialog region is big, the space between the message and the button may be bigger than the space margin.

Reference

SFZQuestionDialog::SetFrameSize | SFZQuestionDialog::SetSpaceSize