1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/StringItem.h hrev46985 10 * src/kits/interface/StringItem.cpp hrev46985 11 */ 12 13 14/*! 15 \file StringItem.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BStringItem class definition. 19*/ 20 21 22/*! 23 \class BStringItem 24 \ingroup interface 25 \ingroup libbe 26 \brief A list item of a text string used as a member of a BListView 27 or BOutlineListView. 28 29 \since BeOS R3 30*/ 31 32 33/*! 34 \fn BStringItem::BStringItem(const char* text, uint32 level, bool expanded) 35 \brief Creates a new BStringItem object which displays the \a text string. 36 37 The \a level and \a expanded parameters only apply to string items attached 38 to a BOutlineListView and are passed unchanged to the BListItem constructor. 39 40 \param text The \a text to display. 41 \param level The \a level of the item in a BOutlineListView. 42 \param expanded Whether or not the item is \a expanded in a 43 BOutlineListView. 44 45 \since BeOS R3 46*/ 47 48 49/*! 50 \fn BStringItem::BStringItem(BMessage* archive) 51 \brief Archive constructor. 52 53 \param archive The message \a archive to construct the string item from. 54 55 \since BeOS R3 56*/ 57 58 59/*! 60 \fn BStringItem::~BStringItem() 61 \brief Destructor, frees the memory used by the string. 62 63 \since BeOS R3 64*/ 65 66 67/*! 68 \name Archiving 69*/ 70 71 72//! @{ 73 74 75/*! 76 \fn BArchivable* BStringItem::Instantiate(BMessage* archive) 77 \brief Creates a new BStringItem object from an \a archive message. 78 79 \return A newly created BStringItem object or \c NULL if the message 80 doesn't contain an archived BStringItem. 81 82 \since BeOS R3 83*/ 84 85 86/*! 87 \fn status_t BStringItem::Archive(BMessage* archive, bool deep) const 88 \brief Archives the the BStringItem object into the \a archive message. 89 90 \param archive A pointer to the BMessage to archive the object into. 91 \param deep This parameter has no effect for this class. 92 93 \return A status code, \c B_OK if everything went well or an error code 94 otherwise. 95 \retval B_OK The object was archived successfully. 96 \retval B_NO_MEMORY Ran out of memory while archiving the object. 97 98 \since BeOS R3 99*/ 100 101 102//! @} 103 104 105/*! 106 \fn void BStringItem::DrawItem(BView* owner, BRect frame, bool complete) 107 \brief Hook method called when the string item is drawn. 108 109 The background is drawn either \c B_LIST_BACKGROUND_COLOR or 110 \c B_LIST_SELECTED_BACKGROUND_COLOR depending on whether the item is 111 selected or not. 112 113 Similarly, the text is drawn either \c B_LIST_ITEM_TEXT_COLOR or 114 \c B_LIST_SELECTED_ITEM_TEXT_COLOR. 115 116 The text is drawn in a lighter color if the item is disabled to indicate 117 that it may not be selected. A darker color is used instead if 118 \c B_LIST_BACKGROUND_COLOR is set to a dark color. 119 120 \param owner The string item's parent. 121 \param frame The frame to draw in. 122 \param complete Whether or not to draw the background in addition to the 123 item's contents. 124 125 \sa IsSelected() 126 \sa IsEnabled() 127 128 \since BeOS R3 129*/ 130 131 132/*! 133 \fn void BStringItem::SetText(const char* text) 134 \brief Sets the \a text string displayed by the item. The memory used by the 135 old string is freed. 136 137 \param text The \a text string to set in a C-string. 138 139 \since BeOS R3 140*/ 141 142 143/*! 144 \fn const char* BStringItem::Text() const 145 \returns The text set to the item. 146 147 \returns the text set to the item as a C-string. 148 149 \since BeOS R3 150*/ 151 152 153/* 154 \fn void BStringItem::Update(BView* owner, const BFont* font) 155 \brief Hook method that's called when the \a owner changes. 156 157 This method gets called when the string item is added to a list view. 158 159 The default implementation sets the width of the list item to the width of 160 \a owner and sets the height to fit \a font. 161 162 \param owner The list item's new \a owner. 163 \param font The font set to the list item's current \a owner. 164 165 \since BeOS R3 166*/ 167 168 169/*! 170 \fn float BStringItem::BaselineOffset() const 171 \brief Returns the offset from the top of the frame to the base line of 172 the text. 173 174 The baseline is the line upon which the letters "sit" and below which 175 descenders extend. This value is set in the Update() method. 176 177 This may be overridden by derived classes to set the base line offset. 178 179 \returns The offset to the baseline of the text as a float. 180 181 \since Haiku R1 182*/ 183