From 459706ee4dc38a39a00892b6491480f0dcd208b8 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Fri, 5 Dec 2014 20:30:28 -0500 Subject: [PATCH] Update BView and BStringView docs ... based on Adrien's suggestions. * Add \warning back to BView::ResizeToPreferred(), add \remark to highlight methods only appropriate to use as part of a BLayout. * Clarify BView::SetFont() method and refer to BFont docs. * Clarify BStringView::SetText(), Text(), and Draw(). * add field descriptions for BStringView::Instantiate(). --- docs/user/interface/StringView.dox | 37 +++++++++++------ docs/user/interface/View.dox | 66 +++++++++++++++--------------- 2 files changed, 58 insertions(+), 45 deletions(-) diff --git a/docs/user/interface/StringView.dox b/docs/user/interface/StringView.dox index c79dbbc04e..61cfe34611 100644 --- a/docs/user/interface/StringView.dox +++ b/docs/user/interface/StringView.dox @@ -88,9 +88,6 @@ \fn BStringView::BStringView(BMessage* archive) \brief Archive constructor. - The string view's text, alignment, and view flags can be set using this - constructor. - \warning This method is usually not called directly. If you want to build a string view from an archive message you should call Instantiate() instead which can handle errors properly. @@ -121,6 +118,16 @@ \fn BArchivable* BStringView::Instantiate(BMessage* archive) \brief Creates a new BStringView object from an \a archive message. + The string view's text, and alignment can be set using this method. + - The "_text" property is a \c B_STRING_TYPE containing the text of + the string view. + - The "_align" property is a \c B_INT32_TYPE containing the string + view's alignment flag. This should be casted to an alignment type. + Choices are: + - \c B_ALIGN_LEFT + - \c B_ALIGN_RIGHT + - \c B_ALIGN_CENTER + \return A newly created BStringView object or \c NULL if the message doesn't contain an archived BStringView. @@ -196,17 +203,17 @@ /*! \fn void BStringView::Draw(BRect updateRect) - \brief Draws the area of the string view that intersects \a updateRect. + \brief Draws the area of the view that intersects \a updateRect. - \note This is an hook method called by the Interface Kit, you don't - have to call it yourself. If you need to forcefully redraw the - string view consider calling Invalidate() instead. + \remark This is an hook method called by the Interface Kit, you don't have to + call it yourself. If you need to forcefully redraw the view consider + calling Invalidate() instead. \param updateRect The rectangular area to be drawn. - \sa BView::Draw() - \since BeOS R3 + + \see BView::Draw() */ @@ -332,8 +339,12 @@ /*! \fn void BStringView::SetText(const char* text) - \brief Sets the \a text string displayed by the string view. The memory - used by the old string is freed. + \brief Sets the \a text string displayed by the string view. + + The \a text string is copied, BStringView does not take ownership + of the memory referenced by the pointer so you should free it yourself + afterwords. If a string has previously been set on the string view, the + memory used by the old string is freed before setting the new string. \param text The \a text string to set. @@ -343,9 +354,9 @@ /*! \fn const char* BStringView::Text() const - \brief Returns the text currently set to the string view. + \brief Returns the text currently set on the string view. - \returns The text set to the string view. + \returns The string view's text as a const char*. \since BeOS R3 */ diff --git a/docs/user/interface/View.dox b/docs/user/interface/View.dox index 53fea653e9..91f9e8cc84 100644 --- a/docs/user/interface/View.dox +++ b/docs/user/interface/View.dox @@ -741,7 +741,7 @@ SetViewColor(Parent()->ViewColor()); \brief Creates a new BView object from the \a data message. \returns A newly created BView object or \c NULL if the message doesn't - contain an archived BView. + contain an archived BView. \since BeOS R3 */ @@ -1403,7 +1403,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::Flush() const \brief Flushes the attached window's connection to App Server. - If the view isn't attached to a window, Flush() does nothing. + \note If the view isn't attached to a window, Flush() does nothing. \since BeOS R3 */ @@ -1454,7 +1454,8 @@ SetViewColor(Parent()->ViewColor()); \brief Resizes the view to its preferred size keeping the position of the left top corner constant. - It is not recommended to use this method for views that are part of a BLayout. + \warning It is not recommended to use this method for views that are part + of a BLayout. \since BeOS R3 */ @@ -1502,7 +1503,8 @@ SetViewColor(Parent()->ViewColor()); BHandler* replyTo) \brief Initiates a drag-and-drop session. - This method only works if the BView objects are attached to a window. + \warning This method only works if the BView objects are attached to a + window. \param message Contains data to be dragged and dropped on the destination view. The caller retains responsibility for this object. @@ -1521,7 +1523,8 @@ SetViewColor(Parent()->ViewColor()); BPoint offset, BHandler* replyTo) \brief Initiates a drag-and-drop session of an \a image. - This method only works if the BView objects are attached to a window. + \warning This method only works if the BView objects are attached to a + window. \param message Contains data to be dragged and dropped on the destination view. The caller retains responsibility for this object. @@ -1543,7 +1546,8 @@ SetViewColor(Parent()->ViewColor()); \brief Initiates a drag-and-drop session of an \a image with drawing_mode set by \a dragMode. - This method only works if the BView objects are attached to a window. + \warning This method only works if the BView objects are attached to a + window. \param message Contains data to be dragged and dropped on the destination view. The caller retains responsibility for this object. @@ -2171,15 +2175,13 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::SetFont(const BFont* font, uint32 mask) \brief Set the font of the view. - By passing \c B_FONT_ALL to the \a mask parameter as is the default all font - properties from \a font are set on the view. + By passing \c B_FONT_ALL to the \a mask parameter as is the default all + font properties from \a font are set on the view. - \param font A pointer to a BFont object to set. Choices include: - - \c be_plain_font - - \c be_bold_font - - \c be_fixed_font - \param mask A mask of the following values to determine what font properties - to set: + \param font A pointer to a const BFont object to set on the view. + \param mask A mask to determine what font properties to set, either pass + in \c B_FONT_ALL to set all font properties or create a mask + containing one or more of the following values to set: - \c B_FONT_FAMILY_AND_STYLE - \c B_FONT_SPACING - \c B_FONT_SIZE @@ -2189,6 +2191,8 @@ SetViewColor(Parent()->ViewColor()); - \c B_FONT_ROTATION - \c B_FONT_FLAGS + \see BFont for more details. + \since BeOS R3 */ @@ -3959,7 +3963,7 @@ SetViewColor(Parent()->ViewColor()); \fn BSize BView::MinSize() \brief Return the minimum size of the view. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \return The minimum size of the view as a BSize. @@ -3973,7 +3977,7 @@ SetViewColor(Parent()->ViewColor()); \fn BSize BView::MaxSize() \brief Return the maximum size of the view. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \return The maximum size of the view as a BSize. @@ -3987,7 +3991,7 @@ SetViewColor(Parent()->ViewColor()); \fn BSize BView::PreferredSize() \brief Return the preferred size of the view. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \return The preferred size of the view as a BSize. @@ -4001,7 +4005,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::SetExplicitMinSize(BSize size) \brief Set this view's min size, to be used by MinSize(). - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \sa BAbstractLayout::SetExplicitMinSize() @@ -4013,7 +4017,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::SetExplicitMaxSize(BSize size) \brief Set this view's max size, to be used by MaxSize(). - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \sa BAbstractLayout::SetExplicitMaxSize() @@ -4025,7 +4029,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::SetExplicitPreferredSize(BSize size) \brief Set this view's preferred size, to be used by PreferredSize(). - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \sa BAbstractLayout::SetExplicitPreferredSize() @@ -4037,7 +4041,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::SetExplicitAlignment(BAlignment alignment) \brief Set this view's alignment, to be used by Alignment(). - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \sa BAbstractLayout::SetExplicitAlignment() @@ -4049,8 +4053,6 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::SetLayout(BLayout* layout) \brief Sets the \a layout of the view. - This is only meaningful if the view is part of a BLayout. - \param layout The \a layout to set. \since Haiku R1 @@ -4061,7 +4063,7 @@ SetViewColor(Parent()->ViewColor()); \fn BLayout* BView::GetLayout() const \brief Get the layout of the view. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \returns The layout of the view. @@ -4073,7 +4075,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::InvalidateLayout(bool descendants) \brief Invalidate layout. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \param descendants Also invalidate its children views. @@ -4085,7 +4087,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::EnableLayoutInvalidation() \brief Enable layout invalidation. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \since Haiku R1 */ @@ -4095,7 +4097,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::DisableLayoutInvalidation() \brief Disable layout invalidation. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \since Haiku R1 */ @@ -4105,7 +4107,7 @@ SetViewColor(Parent()->ViewColor()); \fn bool BView::IsLayoutInvalidationDisabled() \brief Returns whether or not layout invalidation is disabled. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \return \c true of layout invalidation is disabled, \c false otherwise. @@ -4117,7 +4119,7 @@ SetViewColor(Parent()->ViewColor()); \fn bool BView::IsLayoutValid() const \brief Returns whether or not the layout is valid. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \brief Returns \c true if the layout is valid, \c false otherwise. @@ -4146,7 +4148,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::Layout(bool force) \brief Layout the view. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \param force If \c true layout even if valid. @@ -4158,7 +4160,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::Relayout() \brief Relayout the view. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \since Haiku R1 */ @@ -4168,7 +4170,7 @@ SetViewColor(Parent()->ViewColor()); \fn void BView::DoLayout() \brief Layout view within the layout context. - This is only meaningful if the view is part of a BLayout. + \remark This is only meaningful if the view is part of a BLayout. \since Haiku R1 */