FCL/sf/mw/hb: comparison src/hbwidgets/popups/hbinputdialog.cpp

equal deleted inserted replaced

-:06ff229162e9
+:11d3954df52a
 /*!
 @beta
 @hbwidgets
 \class HbInputDialog
-\brief HbInputDialog creates a modal dialog for the user to get some information in the form of text or numbers.
+\brief HbInputDialog is a convenient class for getting user inputs.
 Based on the \InputMode user can enter text, int, double or an IP address. InputDialog can have one or two line edit input fields.
-HbInputDialog by default will have a label to display a descriptive text for the line edit input field and,
+\image html inputdialog.png  "An Input dialog with prompt text and a user input field."
-OK and Cancel buttons.
+HbInputDialog by default will have a label to display a descriptive text which gives information on the user input field,
+an edit field for entering text and,two action buttons.
 example code example:
 \code
+HbInputDialog *object = new HbInputDialog();
+\endcode
+The HbDialog::open( QObject* receiver, const char* member ) method  from the HbDialog is used to show the HbInputDialog.
+The open method can be attached with a SLOT of the format finished(HbAction*). When the open is used with a slot then the slot
+will be invoked once the user does any action such as accept or reject (The Ok or Cancel press).
+below is the declaration of the slot.
+\code
+public slots :
+void dialogClosed(HbAction *action);
+\endcode
+below code shows how the open method can be called using this slot.
+\code
 HbInputDialog *object = new HbInputDialog(parent);
-object->show();
+object->open(this,SLOT(dialogClosed(HbAction*)));
 \endcode
-Four static convenience API's are provided: getText(), getInteger(), getDouble(), and getIp()
+A sample slot definition is shown below
+\code
+void dialogClosed(HbAction *action)
+{
+HbInputDialog *dlg=static_cast<HbInputDialog*>(sender());
+if(dlg->actions().first() == action) { // user is clicked OK
+//Get the string enter by user
+QString myString = dlg->value().toString();
+//Do the action here
+}
+else if(dlg->actions().at(1) == action) {
+// user is clicked CANCEL
+}
+}
+\endcode
+In HbInputDialog four static convenience API's are provided: getText(), getInteger(), getDouble(), and getIp()
 static API's can be used to quickly get an input from user.
 \enum HbInputDialog::InputMode
-\value \b TextInput When this value is set as Input mode, input dialog accepts text input in its
+\value \b TextInput When this value is set as Input mode, Input Dialog accepts text input in its
 correspoinding line edit field.
-\value \b IntInput When this value is set as Input mode, input dialog accepts Integer input in its
+\value \b IntInput When this value is set as Input mode, Input Dialog accepts Integer input in its
 correspoinding line edit field.
-\value \b RealInput When this value is set as Input mode, input dialog accepts double or float input in its
+\value \b RealInput When this value is set as Input mode, Input Dialog accepts double or float input in its
 correspoinding line edit field.
-\value \b IpInput When this value is set as Input mode, input dialog accepts Ip address as input in its
+\value \b IpInput When this value is set as Input mode, Input Dialog accepts Ip address as input in its
 correspoinding line edit field.
 */
 HbInputDialog::~HbInputDialog()
 {
 }
 /*!
-Sets the input mode of the primary(Top/default)line edit in the query widget.
+Sets the input mode of the user field. The default InputMode is TextInput.
+The other available modes are IntInput,RealInput and IpInput.
-The default InputMode is TextInput
 \param mode. InputMode can be TextMode, IntMode, RealMode and Ip address mode.
 each mode will affect how the line edit filters its input.
-\param row. value 0 or 1
+\param row. This parameter indicates which row of the field.0 (by default) means the
+the first user field and 1 means second user field.
 \sa inputMode()
 */
 void HbInputDialog::setInputMode(InputMode mode ,int row)
 {
 Q_D(HbInputDialog);
 d->setInputMode(mode,row);
 }
 /*!
-Returns input mode for top/default line edit.
+Returns input mode of the user field.The default InputMode is TextInput.
-The default InputMode is TextInput
+\param row This parameter indicates which row of the field.0 means the
+the first user field and 1 means second user field.
-\param row. value 0 or 1
 \sa setInputMode()
 */
 HbInputDialog::InputMode HbInputDialog::inputMode(int row) const
 {
 }
 }
 }
 /*!
-Sets the prompt \a text for top/default line edit.
+Sets the prompt text for the user field. This prompt text text can be very descriptive like username,password etc.
-\param text. Text for the label which describes the purpose of the corresponding input line edit field.
+\param text The des
-\param row. value 0 or 1
+\param row This parameter indicates which row of the user field.0 (by default) means the
+the first user field and 1 means second user field.
 \sa promtText()
 */
 void HbInputDialog::setPromptText(const QString &text, int row)
 {
 Q_D(HbInputDialog);
 d->setPromptText(text, row);
 }
 /*!
-Returns prompt text for top/default line edit.
+Returns descriptive prompt text.
-the default is null string.
-\param row. value 0 or 1
+\param row This parameter indicates which row of the field. 0 means the
+the user field in the first row and 1 means user field in the second row.
 \sa setPromptText()
 */
 QString HbInputDialog::promptText(int row) const
 {
 Q_D(const HbInputDialog);
 return d->promptText(row);
 }
 /*!
-Sets the top/default line edit value in \a text format.
+Sets the value for the user input field.The value should in sync HbInputDialog::InputMode of the field.
-\param value. user defined value for the default line edit.
+\param value The value that should be presented to the user.
-\param row. value 0 or 1
+\param row This parameter indicates which row of the user field.0 (by default) means the
+the first user field and 1 means second user field.
 \sa value()
 */
 void HbInputDialog::setValue(const QVariant &value,int row)
 {
 Q_D(HbInputDialog);
 d->setText(value.toString(),row);
 }
 /*!
-Returns top/default line edit value as QVariant object.
+This returns the value of the user field row. The return type is QVariant which can be converted to
+corresponding type based on HbInputDialog::InputMode of the field.
-\param row. value 0 or 1
+\param row This parameter indicates which row of the user field.0 (by default) means the
+the first user field and 1 means second user field
 \sa setValue()
 */
 QVariant HbInputDialog::value(int row) const
 {
 Q_D(const HbInputDialog);
 return QVariant(d->text(row));
 }
 /*!
-Sets the visibility of bottom line edit and prompt text.
+HbInputDialog is capable of showing one or two user input fields. This can be set using this function.
+By default this is false and only first row is visible.
-\param visible true or false.
+\param visible true or false. If true then two user fields will be visible otherwise one.
 \sa isAdditionalRowVisible()
 */
 void HbInputDialog::setAdditionalRowVisible(bool visible)
 {
 Q_D(HbInputDialog);
 d->setAdditionalRowVisible(visible);
 }
 /*!
-Returns the visibility of secondary row(bottom line edit and prompt text).
+Returns the visibility of second row user input field.The default is false.
-the default is false
 \sa setAdditionalRowVisible()
 */
 bool HbInputDialog::isAdditionalRowVisible()
 {
 Q_D(HbInputDialog);
 return d->isAdditionalRowVisible();
 }
 /*!
-Validator is used to validate the content and cursor movements.
+This API allows the user to set any validator to the user input field.
-\param validator. Validator uses undo stack to back out invalid changes. Therefore undo
+\param validator Validator uses undo stack to back out invalid changes. Therefore undo
 is enabled when validator is set.
-\sa HbAbstractEdit::setValidator
+	\param row This parameter indicates which row of the user field.0 means the
+the first user field and 1 means second user field
+\sa HbAbstractEdit::validator
 */
 void HbInputDialog::setValidator(HbValidator *validator,int row)
 {
 Q_D(HbInputDialog);
 if( (row == 0) && (d->mContentWidget->mEdit1) ) {
 d->mContentWidget->mEdit2->setValidator(validator);
 }
 }
 /*!
-Returns the validator of the inputDialog's line edit.
+This API returns the validator of the corresponding user input row.
-\param row. A value 0 or 1
+\param row This parameter indicates which row of the user field.0 (by default) means the
+the first user field and 1 means second user field
 \sa setValidator()
 */
 HbValidator * HbInputDialog::validator(int row) const
 {
 }
 return NULL;
 }
 /*!
-returns the lineEdit pointer. will return NULL if row is greater than 2.
+This returns the editor instance used in HbInputDialog.
+\param row This parameter indicates which row of the user field.0 (by default) means the
-\param row. A value 0 or 1
+the first user field and 1 means second user field
 */
 HbLineEdit* HbInputDialog::lineEdit(int row) const
 {
 Q_D(const HbInputDialog);
 if( (row == 0) && (d->mContentWidget->mEdit1) ) {
 }
 return NULL;
 }
 /*!
-sets the echo mode for the given row.
+sets the echo mode for the user input fiels. The echo mode is defined in HbLineEdit.
+Normal, NoEcho, Password, PasswordEchoOnEdit are the different echo modes supportted in HbLineEdit.
-\param echoMode
-\param row. A value 0 or 1
+\param echoMode which can be HbLineEdit::Normal, HbLineEdit::NoEcho, HbLineEdit::Password or HbLineEdit::PasswordEchoOnEdit.
-\sa HbLineEdit::setEchoMode
+\param row This parameter indicates which row of the user field.0 (by default) means the
+the first user input field and 1 means second user input field
+\sa echoMode() , HbLineEdit::setEchoMode()
 */
 void HbInputDialog::setEchoMode(HbLineEdit::EchoMode echoMode,int row)
 {
 Q_D(HbInputDialog);
 if( (row == 0) && (d->mContentWidget->mEdit1) ) {
 }
 }
 /*!
 \reimp
-Initializes \a option with the values from this HbInputDialog.
 */
 void HbInputDialog::initStyleOption(HbStyleOptionInputDialog *option) const
 {
 Q_D(const HbInputDialog);
 HbDialog::initStyleOption(option);
 option->additionalText = d->mPromptAdditionalText;
 }
 /*!
 \reimp
-updatePrimitives.
 */
 void HbInputDialog::updatePrimitives()
 {
 Q_D(HbInputDialog);
 HbDialog::updatePrimitives();
 style()->updatePrimitive(d->mContentWidget->mLabel2, HbStyle::P_InputDialog_additionaltext, &option);
 }
 }
 /*!
-Returns the echoMode of line edit. returns -1 if row is more than 2.
+Returns the echoMode of the user input field.It returns HbLineEdit::EchoMode.
-\param row. A value 0 or 1
+\param row This parameter indicates which row of the user field.0  means the
+the first user input field and 1 means second user input field
 \sa setEchoMode()
 */
 HbLineEdit::EchoMode HbInputDialog::echoMode(int row) const
 {
 }
 return HbLineEdit::EchoMode(-1);//
 }
 /*!
-Static convenience function for creating an input dialog to get a string from the user.
+This is a static convenience function for creating an Input Dialog and to get a string data from the the user. The Application can use this
-\a label is the text which is shown to the user (it should
+function in order to get any text data from user like username,search data etc. This API allows a slot to be passed as a param. This slot will
-say what should be entered). \a text is the default text which is
+be invoked when the user does the action like OK press or CANCEL press.
-placed in the line edit. If \a ok is non-null \e *\a ok will be
-set to true if the user pressed \gui OK and to false if the user pressed
+HbInputDialog::getText(iTitle,this,SLOT(dialogClosed(HbAction*)),iText);  iTitle is the prompt text.dialogClosed will be invoked when the user does the action.
-\gui Cancel. The dialog's parent is \a parent. The dialog will be
+Please refer the class documentation to know how to handle the slot.
-modal.
+\param label The prompt text which gives information on user input field.
-This function return data has to be queried in the finished(HbAction*) slot.
+\param receiver The instance where the slot is declared.
+\param member The slot which has dialogClosed(HbAction*) signature.
+\param text The default text that should be presented to the user.
+\param scene The scene parameter.
+\param parent The parent item for the dialog.
 \sa getInteger(), getDouble(), getIp()
 */
 void HbInputDialog::getText(const QString &label,
 QObject *receiver,
 const char* member,
 dlg->open(receiver,member);
 }
 /*!
-Static convenience function to get an integer input from the
+This is a static convenience function for creating an Input Dialog and to get an integer data from the the user. The Application can use this
-user.\a label is the text which is shown to the user
+function in order to get any integer data from user like year , any number etc. This API allows a slot to be passed as a param. This slot will
-(it should say what should be entered). \a value is the default
+be invoked when the user does the action like OK press or CANCEL press.
-integer which the spinbox will be set to.
-If \a ok is non-null *\a ok will be set to true if the user
+HbInputDialog::getInt(iTitle,this,SLOT(dialogClosed(HbAction*)),iText);  iTitle is the prompt text.dialogClosed will be invoked when the user does the action.
-pressed \gui OK and to false if the user pressed \gui Cancel. The
+Please refer the class documentation to know how to handle the slot.
-dialog's parent is \a parent. The dialog will be modal.
+\param label The prompt text which gives information on user input field.
-This function return data has to be queried in the finished(HbAction*) slot.
+\param receiver The instance where the slot is declared.
+\param member The slot which has dialogClosed(HbAction*) signature.
+\param value The default value that should be presented to the user.
+\param scene The scene parameter.
+\param parent The parent widget for the dialog.
 \sa getText(), getDouble(), getIp()
 */
 void HbInputDialog::getInteger(const QString &label,
 QObject *receiver,
 const char *member,
 dlg->setValue(QString::number(value));
 dlg->setAttribute(Qt::WA_DeleteOnClose);
 dlg->open(receiver,member);
 }
 /*!
-Static convenience function to get a floating point number from
+This is a static convenience function for creating an Input Dialog and to get a double data from the the user. The Application can use this
-the user.\a label is the text which is shown to the user
+function in order to get any double data from user. This API allows a slot to be passed as a param. This slot will
-(it should say what should be entered). \a value is the default
+be invoked when the user does the action like OK press or CANCEL press.
-floating point number that the line edit will be set to.
+HbInputDialog::getDouble(iTitle,this,SLOT(dialogClosed(HbAction*)),iText);  iTitle is the prompt text.dialogClosed will be invoked when the user does the action.
-If \a ok is non-null, *\a ok will be set to true if the user
+Please refer the class documentation to know how to handle the slot.
-pressed \gui OK and to false if the user pressed \gui Cancel. The
-dialog's parent is \a parent. The dialog will be modal.
+\param label The prompt text which gives information on user input field.
+\param receiver the instance where the slot is declared.
-This function return data has to be queried in the finished(HbAction*) slot.
+\param member the slot which has dialogClosed(HbAction*) signature.
+\param value the default value that should be presented to the user.
+\param scene the scene parameter.
+\param parent the parent widget for the dialog.
 \sa getText(), getInteger(), getIp()
 */
 void HbInputDialog::getDouble(const QString &label,
 QObject *receiver,
 const char *member,
 dlg->open(receiver,member);
 }
 /*!
-Static convenience function to get an ip address from
+This is a static convenience function for creating an Input Dialog and to get an IP information from the the user. This API allows a slot to be passed as a param. This slot will
-the user.\a label is the text which is shown to the user
+be invoked when the user does the action like OK press or CANCEL press.
-(it should say what should be entered). \a address is the default
-QHostAddress that the line edit will be set to.
+HbInputDialog::getIp(iTitle,this,SLOT(dialogClosed(HbAction*)),iText);  iTitle is the prompt text.dialogClosed will be invoked when the user does the action.
+Please refer the class documentation to know how to handle the slot.
-If \a ok is non-null, *\a ok will be set to true if the user
-pressed \gui OK and to false if the user pressed \gui Cancel. The
+\param label The prompt text which gives information on user input field.
-dialog's parent is \a parent. The dialog will be modal.
+\param receiver the instance where the slot is declared.
+\param member the slot which has dialogClosed(HbAction*) signature.
-This function return data has to be queried in the finished(HbAction*) slot.
+\param ipaddress the default value that should be presented to the user.
+\param scene the scene parameter.
+\param parent the parent widget for the dialog.
 \sa getText(), getInteger(), getDouble()
 */
 void HbInputDialog::getIp(const QString &label,
 QObject *receiver,
 const char *member,
 const QString &ipaddress,
 QGraphicsScene *scene,
 HbInputDialog *dlg = new HbInputDialog(parent);
 if(scene && !parent) {
 scene->addItem(dlg);
 }
 dlg->setPromptText(label);
-	dlg->setValue(ipaddress);
+dlg->setValue(ipaddress);
 dlg->setInputMode(IpInput);
 dlg->open(receiver,member);
 }
 #include "moc_hbinputdialog.cpp"

changeset 3	11d3954df52a
parent 2	06ff229162e9
child 6	c3690ec91ef8