RFC: semantic of KDialog::exec() result etc.

[Friedrich W. H. Kossebau]

Hi,

"KDialog" is a "QDialog". So the semantics of "QDialog" should be valid also 
with "KDialog", right? Reading
http://doc.trolltech.com/4.2/qdialog.html
"QDialog::exec()" is said to return a "QDialog::DialogCode" result.

But "KDialog" does not, instead it currently even mixes "QDialog::DialogCode" 
with "KDialog::ButtonCode" (see "KDialog::slotButtonClicked( int button )"), 
both are not compatible (e.g. "QDialog::Accepted" and "KDialog::Help" are 
both 1).
I found this, because it makes pressing "Cancel" in 
e.g. "KMessageBox::createKMessageBox(...)" not work currently 
(returns "QDialog::Rejected", which is != KDialog::Cancel).

So how to solve?
My favourite solution is based on this idea:
A dialog is embedded in a workflow/process (if not modal). So a dialog is like 
a function call (cmp. "dialog.exec()"), which simply includes the user into 
the operation. If the user cancels the dialog it should be treated like a 
failing function. I think this is accepted standard.
The success/product of a function call is usually returned in the result. And 
a standard is to return false/0 to indicate a fail. This goes together with 
QDialog::Rejected being 0 (and conflicts with returning KDialog::Cancel==32.)
For all processes that can be cancelled the dialog offers the option "Cancel", 
for all others not.

I see following usages of a KDialog:
* info window: e.g. "I am done". There "Cancel" makes never sense. (They are 
no dialogs really [0].) Their button is "Close".
* accepting (with the option to cancel), cmp "Ok" (&"Cancel"). This includes 
paged dialogs, where the "Ok" button would read "Finish", once parameters are 
complete. This is different from the following:
* alternating options which end the dialog (but do not cancel the process), 
currently defaulted/named to "Yes" and "No" [1]. "Cancel" optional.
* "Close" for a dialog which has no effect on closing [2], so no "Cancel" 
needed.
* progress/monitor windows: "Cancel" for stopping the process, "Close" for 
closing the window while/after the process.
* any other?

[1] The code currently closes the dialog only 
on "Cancel", "Ok", "Close", "Yes", and "No". So practically all questions 
with more than two fixed options (remember that cancelling is rejecting the 
question/process) are to add parameter field(s) to the dialog. I guess this 
is due to good usability? Should be documented then. ...found, there are 
three options with e.g. accepting storing passwords for websites  
(html_formimpl.cpp). Is there a senseful upper limit to the number? I choose 
here 5.
And aren't Multi-Options and "Okay" mutually exlusive?

[2] Shouldn't "Close" and "Okay" be mutually exclusive? Currently the code 
allows both to be added to a KDialog box. Same for "Cancel" and "Close".

So given this all I would propose to build on the "QDialog::DialogCode" and 
add a "KDialog::ResultCode" enum like this:

	enum ResultCode {
	  // for cancelling
	  Rejected = 0;
	  Cancelled = 0;
	  // for okay//finish//close/e.g. yes
	  Accepted = 1;
	  Finished = 1;
	  Closed = 1;
	  Selected1 = 1;
	  // e.g. no
	  Selected2 = 2;
	  // there are usages for three
	  Selected3 = 3;
	  // there were five closing buttons before,
	  // so stay with it if someone uses all
	  Selected4 = 4;
	  Selected5 = 5;
	};

Makes sense? Or is it wrong to overload the enums? But after all the names 
should not be used together. All the KDialog uses I found so far would fit 
into this picture. Are there usability problems?
"ButtonCodes" and "setButtons(...)" and slots/signals would have to be 
adapted, but that will follow easily.

Or is there any plan to go with QMessageBox anyway?

Regards
Friedrich

PS: QMessageBox breaks the semantic, too. But we should/can do better, right?