KMessage/KMessageHandler: a core/ui seperation for displaying message.

[Frans Englich]

On Sunday 28 May 2006 19:02, Matt Rogers wrote:
> On Sunday 28 May 2006 13:16, Frans Englich wrote:
> > On Sunday 28 May 2006 17:06, Michaël Larouche wrote:
[...]
> > * I would like to put KMessage and KMessageHandler in separate files to
> > make things easier to navigate/less to include, etc.
>
> how is it easier?

You don't have to be familiar with the API or agree with the author's way of 
thinking in order to know where things reside. You just say class "X" is in 
"X.h". Like Qt. You also include less.

But really, this is not that important to me. It also depends on how the API 
works out.

> > * Make the values in MessageType OR'able(1, 2, 4, 8), such that they
> > later on can be used in code which needs to say "I accept these kinds of
> > messages", and so on. Add "typedef QFlags<MessageType> MessageTypes;"
>
> IIRC, values don't need to be OR'able in order to be used by QFlags.

No, they don't "have" to. However, QFlags provide a lot of functionality which 
will behave in weird ways on non-OR'able values. So, by that I wouldn't 
provide a QFlags instantiation since it would give the illusion of "Sure, go 
ahead and use QFlags here," while it actually would break. Why would you want 
to use QFlags on a non-Or'able enum?

However, my reason to making the values OR'able is not because of QFlags, but 
because I would find it practical to have them OR'able.

> Just 
> the proper Q_DECLARE_FLAGS( MessageTypes, MessageType ) macro needs to be
> used instead. AFAIK, "typedef QFlags<MessageType> MessageTypes;" is less
> correct.

Sure. I'd say it's a matter of taste. Q_DECLARE_FLAGS expands to such a 
typedef. I personally don't think it helps much; I think it hides insight 
into what kind of type "FooValues" really is. I don't think Doxygen can see 
through the macro, either. But really, if Q_DECLARE_FLAGS floats people's 
boats I'm fine.

> > * I would put the private parts of KMessage in the cpp instead, since
> > it's public API. (Or no, it wouldn't work?) It would also be nice to get
> > the other private functions out of the public API. Since d-pointers
> > should be added anyway I guess they can be moved there(no?).
>
> what do you mean here? Where do you see the need for d-pointers? I don't
> think a d-pointer in necessary in this case.

I see no need either. But you can't add it when a need for it do exists, so 
unless one feels like having a good day with the crystal ball one should add 
it.

It seems the classes which would need this shouldn't be public API so this 
will perhaps sort out naturally(Oliver's mail).

> > * Doxygen is automatically inherited from super classes, so it's not
> > necessary to @copydoc it(well, Adriaan, correct me on that if I'm wrong).
>
> better safe than sorry, no? :)

Better than being "better safe than sorry", is to know. It this case we can 
know. The comments increases code size, larger files, more to read, parse, 
etc. Comments are inherited; INHERITS_DOCS is set to yes.

[...]

> > * To me it looks like calling KMessage::short(type, text) is identical to
> > calling KMessage::shortMessage(type, text). If they're not, why/when
> > would one want to pass an empty QString to short()? I also think it's
> > better to code information about a message in data, instead of the name
> > of a function call.
>
> where is there a KMessage::short function? I don't see it.

Eh, sorry, message() and shortMessage().

> > * What reasoning concluded KMessage::Sorry is needed? Debug, Warning,
> > Error, Fatal are all "message types" that can easily be distinguished and
> > motivated(imho), and they aren't controversial. For example, it's what
> > DOM 3 Core and Qt happens to have. However, what is a message that is of
> > type Sorry? Why isn't a warning or fatal error of type Sorry? What is the
> > possible actions a message handler can do on Sorry? I think that a need
> > of "Sorry" originates from that this KMessage/KMessageHandler is
> > insufficient in some cases.
>
> This would be analogous to the current static functions in KMessageBox like
> sorry, warning, etc.
>
> You say it's insufficient, but you don't say how. How is it insufficient?

What is a handler supposed to do with a message of type "Sorry"? Can it be 
ignored, like Warning or Debug? Is it potentially critical to proper 
behavior, such as Fatal is? There is no way to tell.

My point with it being insufficient is that the API is not expressible enough 
if application specific things as "Sorry" is baked into it. If "Sorry" is ok, 
I don't see why Important, Alert, InsertYourChoiceHere isn't ok.

By having each message as a class instance, applications can extend reporting 
in a way suitable for them, and kdelibs doesn't have to include the kitchen 
sync. For example, for the next time someone wants to code where a message is 
supposed to end up.

I'm fine with not making KMessageHandler/KMessage adaptable, but I really 
think it shouldn't attempt to adapt to a specific user scenario, such as the 
case of "Sorry". Provide mechanism, not policy.


Cheers,

		Frans