[kde-guidelines] KStyleguide

Thu May 16 20:17:31 UTC 2013

On Thursday 16 May 2013 10:54:32 Dr. Heiko Tietze wrote:
> Am Mittwoch, 15. Mai 2013, 22:25:17 schrieb Thomas Pfeiffer:
> > On Wednesday 15 May 2013 10:03:36 Heiko Tietze wrote:
> > > (I recommend to rethink this
> > > behaviour. If more than these two options are possible, a dropdown menu
> > > perhaps via menu button with close as default fits better than close,
> > > configure, open trash, etc. as shown in the last ticket.) - If more than
> > > one information is shown the notification panels are stacked. - ...
> > 
> > Seems like I missed that ticket. Who proposed to have more than the close
> > and configure buttons at the top?
> > Action specific to a certain notification are shown inline and not at the
> > top, and currently I don't see any other buttons then the aforementioned
> > to
> > there...
> 
> The picture https://git.reviewboard.kde.org/r/110389/file/571/ shows the
> options Open File Manager, Do Nothing, Configure... for Low Disk Space,
> moreover special font at Now playing (which isn't a notification at all),
> and improvable captions (KDialog Notification), certainly because it is an
> example.

> The button "Configure..." and the tool icon contain different settings but
> start similar functions - both are used to configure stuff. Do users
> understand this sophistication? Isn't "Do Nothing" similar to the close
> action? Should we allow those controls, just because one tool provides it?

I'd consider this one an example of a badly designed/implemented notification 
;) Indeed the "Do Nothing" button is completely redundant to the X button. I 
assume that the Configure... button indeed does something different from the 
wrench button (configuring when vs. how to notify), but it still does feel 
weird indeed. I'm not sure if that particular Configure button should be there, 
but even if it stays, it's a very specific case and I don't think that we 
should design the standard around these edge cases. Normally, any configuration 
that does not concern the notification itself should not be accessible from the 
notification, period. Ideally, the configuration of when to notify of low disk 
space should go into the Notifications settings, but I guess that would be a 
whole lot of trouble on the technical side, since it's no-standard.

The "Open File Manager" button, on the other hand, is quite different than the 
X and wrench buttons: The former is a reaction to the notification's *content*, 
whereas the latter two represent actions concerning the notification itself.

And I think this is a valid distinction. The wrench and X buttons are 
"standard" buttons which I see as more akin to the window border buttons of 
application windows, whereas the reaction buttons are part of the actual 
notification content.
Hiding reactions to a notification's content behind a combo button doesn't seem 
to be the right way to me. For example if you are notified of an incoming 
contact request in an instant messenger, you have the options to either allow 
or reject the request. These have nothing to do with the notification itself, 
but with its content, and those are rightly placed within the content.
And since I do not expect any other buttons then close and configure in the 
corner of the notification, I don't think a combo button would be necessary.

What we should write into the HIG, though, is that no reaction button should 
be redundant to either the X or the wrench button. 

> There is no clear match to current reality. A styleguide is of course
> descriptive, but due to it's nature it will become more or less normative.
> Otherwise we wouldn't need it.

It becomes normative in a way that it ensures consistency, but it can still 
reflect an existing solution which we regard as the "gold standard". If no such 
solution exists, we should create it _before_ writing the HIG, because no 
developer wants to be the first one to implement a new HIG. If they see an HIG 
already implemented somewhere, they're much more likely to implement it. At 
least this is what I've experienced withing KDE so far: Developers want to 
know "Where can I see that in action?".

> Dos and Don'ts:
> - Don't add further controls.
> - Don't override default settings.
> - Don't use programing terms for text.

What do you mean by "further controls"? As said above, I find the reaction 
buttons useful. Anything else should indeed not be there and I hope is 
technically not possible. If it is, than the class in kdelibs has to be 
changed.

> The latter is a rather generic advice which should be moved to section 3 if
> we decide to follow my proposal.

Hm, I fear that people may not read it if it's in section 3 because they think 
"Well, I don't have to care about visuals, kdelibs does that for me" and skip 
that section.

> |Am Mittwoch, 15. Mai 2013, 12:07:23 schrieb David Edmundson:
> > Can I suggest we separate the tasks  "how an app developer should use
> > existing KDE libs" and trying to change what the KDE libs do.
> 
> At least Qt shouldn't be part of our styleguide :-).
> I wonder how to decide what is lib specific and what's under dev's control.

That's not for us to decide, but for the developers to know ;) They can tell 
us what devs can control and what they can't in the current state of kdelibs.

> Basically, I like how Microsoft creates the Windows styleguide (except from
> the structure, in particular the design principles). The API function
> MessageBox() [1] can be used to create just the dialog and the styleguide
> [2] referes only to the options that are available.
> 
> [1]
> http://msdn.microsoft.com/en-us/library/windows/desktop/ms645505%28v=vs.85%
> 29.aspx [2]
> http://msdn.microsoft.com/en-us/library/windows/desktop/aa511268.aspx#modal
> DialogBoxes 

I think it would still be helpful to integrate code snippets into the HIG, but 
only describing the available options is what David was suggesting if I've 
understood him correctly.

Cheers,
Thomas