1/* 2 * Copyright 2020 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/SpaceLayoutItem.h hrev43514 10 * src/kits/interface/SpaceLayoutItem.cpp hrev44346 11 */ 12 13 14/*! 15 \file SpaceLayoutItem.h 16 \ingroup layout 17 \brief Provides the BSpaceLayoutItem class. 18 19 \since Haiku R1 20*/ 21 22 23/*! 24 \class BSpaceLayoutItem 25 \ingroup layout 26 \ingroup libbe 27 \brief An empty layout item that expands into empty space based on its size 28 configuration. 29 30 This class is a specialized layout item, that is used to distribute space 31 within one of the layouts. The layout item can be manually configured, but 32 there are also two default varieties. 33 34 The first variety is the \b glue variety. Glue is an element that expands 35 to the maximum space that is available. Let's say, you have a horizontal 36 BGroupLayout. You want a button on the left, and a button on the right, 37 with empty space in the middle. The middle element can be a glue element. 38 The glue will push the right button all the way to the end of the available 39 space. If the host view gets larger, the glue will expand. You can use the 40 static method BSpaceLayoutItem::CreateGlue() to easily create a glue 41 element. 42 43 Another variety is the \b strut. A is a layout item with no minimum size, 44 and a maximum size. This means that the item might be smaller than the 45 maximum size, but it will never be larger than the maximum size. You can 46 use the static methods BSpaceLayoutItem::CreateVerticalStrut() and 47 BSpaceLayoutItem::CreateHorizontalStrut() to create a strut item. 48 49 The default constructor allows you to create a layout item with custom 50 minimum sizes, maximum sizes, preferred sizes and alignments. 51 52 \see Where applicable, the layout builder classes have convenience methods 53 to add glue or struts. See 54 BLayoutBuilder::Group<ParentBuilder>::AddGlue() or 55 BLayoutBuilder::Group<ParentBuilder>::AddStrut(). 56 57 \since Haiku R1 58*/ 59 60 61/*! 62 \fn BSpaceLayoutItem::BSpaceLayoutItem(BSize minSize, BSize maxSize, 63 BSize preferredSize, BAlignment alignment) 64 \brief Create a space layout item with specific properties. 65 66 See the CreateGlue(), CreateVerticalStrut() and CreateHorizontalStruct 67 static methods to create common space items. 68 69 \param minSize The minimum size for this item. 70 \param maxSize The maximum size for this item. 71 \param preferredSize The preferred size for this item. 72 \param alignment The alignment of this item. 73 74 \since Haiku R1 75*/ 76 77 78/*! 79 \fn BSpaceLayoutItem::BSpaceLayoutItem(BMessage *archive) 80 \brief Constructs a BSpaceLayoutItem from an \a archive message. 81 82 This method is usually not called directly, if you want to build a 83 space layout item from an archived message you should call Instantiate() 84 instead because it can handle errors properly. 85 86 \param archive The \ref BMessage that contains the space layout item. 87 88 \since Haiku R1 89*/ 90 91 92/*! 93 \fn virtual BSpaceLayoutItem::~BSpaceLayoutItem() 94 \brief Destructor. 95 96 \since Haiku R1 97*/ 98 99 100/*! 101 \fn virtual BSize BSpaceLayoutItem::MinSize() 102 \copydoc BLayoutItem::MinSize() 103*/ 104 105 106/*! 107 \fn virtual BSize BSpaceLayoutItem::MaxSize() 108 \copydoc BLayoutItem::MaxSize() 109*/ 110 111 112/*! 113 \fn virtual BSize BSpaceLayoutItem::PreferredSize() 114 \copydoc BLayoutItem::PreferredSize() 115*/ 116 117 118/*! 119 \fn virtual BAlignment BSpaceLayoutItem::Alignment() 120 \copydoc BLayoutItem::Alignment() 121*/ 122 123 124/*! 125 \fn virtual void BSpaceLayoutItem::SetExplicitMinSize(BSize size) 126 \copydoc BLayoutItem::SetExplicitMinSize() 127*/ 128 129 130/*! 131 \fn virtual void BSpaceLayoutItem::SetExplicitMaxSize(BSize size) 132 \copydoc BLayoutItem::SetExplicitMaxSize() 133*/ 134 135 136/*! 137 \fn virtual void BSpaceLayoutItem::SetExplicitPreferredSize( 138 BSize size) 139 \copydoc BLayoutItem::SetExplicitPreferredSize() 140*/ 141 142 143/*! 144 \fn virtual void BSpaceLayoutItem::SetExplicitAlignment( 145 BAlignment alignment) 146 \copydoc BLayoutItem::SetExplicitAlignment() 147*/ 148 149 150/*! 151 \fn virtual virtual bool BSpaceLayoutItem::IsVisible() 152 \brief Return the current local visibility of this item. 153 154 The visibility is set explicitly through SetVisible(). By default, the 155 layout item is visible. 156 157 \since Haiku R1 158*/ 159 160 161/*! 162 \fn virtual void BSpaceLayoutItem::SetVisible(bool visible) 163 \brief Set the visibility of this space layout item. 164 165 \param visible The desired visibility of the layout item. 166 167 \since Haiku R1 168*/ 169 170 171/*! 172 \fn virtual BRect BSpaceLayoutItem::Frame() 173 \copydoc BLayoutItem::Frame() 174*/ 175 176 177/*! 178 \fn virtual void BSpaceLayoutItem::SetFrame(BRect frame) 179 \copydoc BLayoutItem::SetFrame() 180*/ 181 182 183/*! 184 \fn static BSpaceLayoutItem* BSpaceLayoutItem::CreateGlue() 185 \brief Create a layout item that acts like glue. 186 187 This type of space layout item has no minimum size, and expands to the 188 maximum available space in all directions. 189 190 \return Creates a new BSpaceLayoutItem and returns ownership to the caller. 191 192 \since Haiku R1 193*/ 194 195 196/*! 197 \fn static BSpaceLayoutItem* BSpaceLayoutItem::CreateHorizontalStrut( 198 float width) 199 \brief Create a layout item that horizontally expands to a maximum 200 \a width. 201 202 The item has no minimum size, meaning that if the total available width is 203 smaller than the maximum \a width, the strut will use the available space. 204 205 \param width The maximum width. 206 207 \return Creates a new BSpaceLayoutItem and returns ownership to the caller. 208 209 \since Haiku R1 210*/ 211 212 213/*! 214 \fn static static BSpaceLayoutItem* BSpaceLayoutItem::CreateVerticalStrut(float height) 215 \brief Create a layout item that vertically expands to a maximum 216 \a height. 217 218 The item has no minimum size, meaning that if the total available height is 219 smaller than the maximum \a width, the strut will use the available space. 220 221 \param height The maximum height. 222 223 \return Creates a new BSpaceLayoutItem and returns ownership to the caller. 224 225 \since Haiku R1 226*/ 227 228 229/*! 230 \fn static BArchivable* BSpaceLayoutItem::Instantiate(BMessage *from) 231 \brief Instantiate the item from the message \a from. 232 233 \since Haiku R1 234*/ 235