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 * Reviewers: 9 * Adrien Destugues, pulkomandy@pulkomandy.tk 10 * 11 * Corresponds to: 12 * headers/os/interface/CardLayout.h hrev43514 13 * src/kits/interface/CardLayout.cpp hrev49019 14 */ 15 16 17/*! 18 \file CardLayout.h 19 \ingroup interface 20 \ingroup layout 21 \brief Provides the BCardLayout class. 22 23 \since Haiku R1 24*/ 25 26 27/*! 28 \class BCardLayout 29 \ingroup layout 30 \ingroup libbe 31 \brief The BCardLayout class is a simple BLayout subclass that 32 arranges the items as a stack of cards with only one card being on top 33 and visible to the user. 34 35 Once you have set up the items in the container, you can select which one 36 is visible using the SetVisibleItem() methods on this class. When there is 37 no item on top, the system's default grey background is shown. 38 39 This view is useful when you have a number of pre-loaded UI elements, and 40 you want to be able to swap between them quickly, while retaining the 41 underlying state. The container itself will retain a fixed size, so from a 42 visual perspective, it is imperative that the items in the stack have 43 comparable dimensions. 44 45 An example usage is for a configuration wizard, where the user will need to 46 complete a number of steps to perform an action. Because you want to the 47 user to experience all these steps as a smooth flow within one window, you 48 can set up the individual pages as views, and add these as cards to the 49 card layout. Then you tie the \em Next and \em Previous buttons to switch 50 between the visible cards using the BCardLayout::SetVisible() methods. 51 52 \since Haiku R1 53*/ 54 55 56/*! 57 \fn BCardLayout::BCardLayout() 58 \brief Create a new card layout. 59 60 \since Haiku R1 61*/ 62 63 64/*! 65 \fn BCardLayout::BCardLayout(BMessage *from) 66 \brief Constructs a BCardLayout \a from an archive message. 67 68 This method is usually not called directly, if you want to build a 69 card layout from an archived message you should call Instantiate() instead 70 because it can handle errors properly. 71 72 \param from The \ref BMessage that contains the card layout. 73 74 \since Haiku R1 75*/ 76 77 78/*! 79 \fn virtual virtual BCardLayout::~BCardLayout() 80 \brief Destructor. 81 82 \since Haiku R1 83*/ 84 85 86/*! 87 \fn BLayoutItem* BCardLayout::VisibleItem() const 88 \brief Get a pointer to the currently visible item. 89 90 \return This method returns a pointer to the currently visible 91 layout item, or \c NULL if there is no card visible. 92 93 \since Haiku R1 94*/ 95 96 97/*! 98 \fn int32 BCardLayout::VisibleIndex() const 99 \brief Get the index of the currently visible item. 100 101 \return Returns the zero-based index, or -1 if there is no item visible. 102 103 \since Haiku R1 104*/ 105 106 107/*! 108 \fn void BCardLayout::SetVisibleItem(int32 index) 109 \brief Set the current visible item to the item at \a index. 110 111 \param index This is a zero-based index for the item you want to display. 112 If the item does not exist (it is lower than 0 or it is higher than 113 the number of items), no item will be displayed and the view will reset 114 to the default grey background. 115 116 \since Haiku R1 117*/ 118 119 120/*! 121 \fn void BCardLayout::SetVisibleItem(BLayoutItem *item) 122 \brief Set the current visible item to \a item. 123 124 \param item A pointer to an item that is already added to this 125 layout. When a reference to an item not on the stack, or \c NULL is 126 passed, then no item will be displayed and the view will reset to the 127 default grey background. 128 129 \since Haiku R1 130*/ 131 132 133/*! 134 \fn virtual BSize BCardLayout::BaseMinSize() 135 \brief Overridden hook method from BAbstractLayout. 136 137 \since Haiku R1 138*/ 139 140 141/*! 142 \fn virtual BSize BCardLayout::BaseMaxSize() 143 \brief Overridden hook method from BAbstractLayout. 144 145 \since Haiku R1 146*/ 147 148 149/*! 150 \fn virtual BSize BCardLayout::BasePreferredSize() 151 \brief Overridden hook method from BAbstractLayout. 152 153 \since Haiku R1 154*/ 155 156 157/*! 158 \fn virtual BAlignment BCardLayout::BaseAlignment() 159 \brief Overridden hook method from BAbstractLayout. 160 161 \since Haiku R1 162*/ 163 164 165/*! 166 \fn virtual bool BCardLayout::HasHeightForWidth() 167 \brief Overridden hook method from BAbstractLayout. 168 169 \since Haiku R1 170*/ 171 172 173/*! 174 \fn virtual void BCardLayout::GetHeightForWidth(float width, float *min, float *max, float *preferred) 175 \brief Overridden hook method from BAbstractLayout. 176 177 \since Haiku R1 178*/ 179 180 181/*! 182 \fn virtual status_t BCardLayout::Archive(BMessage *into, bool deep=true) const 183 \brief Archive this layout \a into a BMessage. 184 185 \param into The message to which to archive into. 186 \param deep When \c true, the children of this layout will also be added. 187 188 \since Haiku R1 189*/ 190 191 192/*! 193 \fn virtual status_t BCardLayout::Perform(perform_code d, void *arg) 194 \brief Overridden hook method from BAbstractLayout. 195 196 \since Haiku R1 197*/ 198 199 200/*! 201 \fn static BArchivable* BCardLayout::Instantiate(BMessage *from) 202 \brief Instantiate a BCardLayout object from message \a from. 203 204 \since Haiku R1 205*/ 206 207 208/*! 209 \fn virtual status_t BCardLayout::AllArchived(BMessage *archive) const 210 \brief Hook method overridden from BArchivable. 211 212 \since Haiku R1 213*/ 214 215 216/*! 217 \fn virtual status_t BCardLayout::AllUnarchived(const BMessage *from) 218 \brief Hook method overridden from BArchivable. 219 220 \since Haiku R1 221*/ 222 223 224/*! 225 \fn virtual status_t BCardLayout::ItemArchived(BMessage *into, 226 BLayoutItem *item, int32 index) const 227 \brief Hook method overridden from BArchivable. 228 229 \since Haiku R1 230*/ 231 232 233/*! 234 \fn virtual status_t BCardLayout::ItemUnarchived(const BMessage *from, 235 BLayoutItem *item, int32 index) 236 \brief Hook method overridden from BArchivable. 237 238 \since Haiku R1 239*/ 240 241 242/*! 243 \fn virtual void BCardLayout::LayoutInvalidated(bool children=false) 244 \brief Hook method overridden from BAbstractLayout. 245 246 \since Haiku R1 247*/ 248 249 250/*! 251 \fn virtual void BCardLayout::DoLayout() 252 \brief Hook method overridden from BAbstractLayout. 253 254 \since Haiku R1 255*/ 256 257 258/*! 259 \fn virtual bool BCardLayout::ItemAdded(BLayoutItem *item, int32 atIndex) 260 \brief Hook method overridden from BAbstractLayout. 261 262 \since Haiku R1 263*/ 264 265 266/*! 267 \fn virtual void BCardLayout::ItemRemoved(BLayoutItem *item, int32 fromIndex) 268 \brief Hook method overridden from BAbstractLayout. 269 270 \since Haiku R1 271*/ 272