window captions

being home with internet on a monday for the first time in a month or so allowed me to check in some small changes to kdelibs. (monday is the "make people recompile everything" day in kdelibs ;) one of these small changes was to the facility to make standard window captions. in kde3 this was KApplication::makeStdCaption(QString, bool, bool) and now it is a static method in kinstance: KInstance::makeStandardCaption(QString, QWidget*, CaptionFlags).

the two non-descript bools are now a flag which defaults to HIGCompliantCaption, but can also include things like ModifiedCaption. the QWidget* is the dialog or window that this caption will be applied to. this should allow other platforms to decide when to tack on application names, etc. in compliance with the native interface guidelines. this particular bit was the result of a thread on kde-core-devel where it was suggested we alter (imho neuter) kde by removing app names from dialogs because every other platform does it. i suggested that we let those other platforms care for their own and do it their way (and now the API allows for that) while leaving us to make independent decisions for kde with the best interests of our users in mind.

personally, i'm wondering which (if any) of the new platform teams will step up and do the necessary work. to me it's a real test of the maturity and commitment, and one that will likely change (hopefully grow) over time.

that said, while making things compile again i noticed a number of "interesting" code snippets related to window captions. so here are some suggestions:

first off, always use KDialog and KMainWindow unless you have very good reasons not to. and no, thinking you might save a few bytes of memory by using QDialog instead is not a good reason. ;) the caption related reason here is that you can then just use setCaption(QString) and setCaption(QString, bool) to set the caption properly. internally, both call KInstance::makeStandardCaption with the correct flags. the version that takes a bool lets one reflect the modified state of the window in the title, so if your app has a document loaded that has been modified by the user (and therefore needs to be saved or have some other action taken on it prior to closing) you can just call setCaption(i18n("Some Caption"), true). yes, this probably should not be using a bool for api readability, but there it stands right now.

i see a lot of manual mucking about with CaptionFlags in the code base. most of it is unnecessary because setCaption should be called instead of directly calling KInstance::makeStandardCaption. i think at least some of this was caused by a fairly brute force scripted porting attempt, but it should be cleaned up now.

if you aren't using KDialog or KMainWindow then you'll need to call KInstance::makeStandardCaption yourself. be sure to pass a pointer to the window along with your caption string and all should be good.