Move documentation for parameter of SfxObjectShell::GetTitle() to include file

A re-design of this API would be a good idea.

Is this function ever called with some specific max length that would
not be one of the magic values? Probably the sanest would be to turn
the magic value constants into a normal (scoped) enum, and have two
separate functions: One that takes no parameter and returns the whole
title (and then let the caller take care of truncating as necessary),
and one that takes such an enum and returns a correspondingly mangled
title. The less magic and defaulted parameters the better.

Change-Id: I9e3aa95fae981c5ed48300b753556fa9074c1166

1 files changed, 39 insertions, 0 deletions

diff --git a/include/sfx2/objsh.hxx b/include/sfx2/objsh.hxx
index 39ed879d9a69..5a47988f1e14 100644
--- a/include/sfx2/objsh.hxx
+++ b/include/sfx2/objsh.hxx
@@ -475,6 +475,45 @@ public:
 
     // Naming Interface
     void                        SetTitle( const OUString& rTitle );
+    /* Small non-zero values of nMaxLen don't mean length, but have a magic meaning:
+       0 (default)
+       the title itself, as it is
+
+       1 (==SFX_TITLE_FILENAME)
+       provides the logical file name without path
+       (under WNT depending on the system settings
+       without extension)
+
+       2 (==SFX_TITLE_FULLNAME)
+       provides the logical file names with full path
+       (remote =>:: com:: sun:: star:: util:: URL)
+
+       3 (==SFX_TITLE_APINAME)
+       provides the logical filename without path
+       and extension
+
+       4 (==SFX_TITLE_DETECT)
+       provides the complete title, if not set yet
+       it will be created from DocInfo or the name of
+       the medium.
+
+       5 (==SFX_TITLE_CAPTION)
+       provides the Title just like MB now in the
+       CaptionBar view
+
+       6 (==SFX_TITLE_PICKLIST)
+       returns the Title, just like MB now would
+       display it in the PickList
+
+       7 (==SFX_TITLE_HISTORY)
+       returns the Title just like MB now would
+       display it in the History
+
+       10 bis USHRT_MAX
+       provides the 'nMaxLength' of the logical
+       file name including the path
+       (remote => css::util::URL)
+    */
     OUString                    GetTitle( sal_uInt16 nMaxLen = 0 ) const;
     void                        InvalidateName();  // Re-set to unnamed