From 46f5821ad15158023327cad1f90a05dbe43f1aa7 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Wed, 11 Dec 2013 16:15:15 -0500 Subject: [PATCH] Add docs for BOutlineListView class --- docs/user/interface/OutlineListView.dox | 627 ++++++++++++++++++ .../images/BOutlineListView_example.png | Bin 0 -> 2775 bytes 2 files changed, 627 insertions(+) create mode 100644 docs/user/interface/OutlineListView.dox create mode 100644 docs/user/interface/images/BOutlineListView_example.png diff --git a/docs/user/interface/OutlineListView.dox b/docs/user/interface/OutlineListView.dox new file mode 100644 index 0000000000..49c3dd4867 --- /dev/null +++ b/docs/user/interface/OutlineListView.dox @@ -0,0 +1,627 @@ +/* + * Copyright 2013 Haiku Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * headers/os/interface/OutlineListView.h hrev46526 + * src/kits/interface/OutlineListView.cpp hrev46526 + */ + + +/*! + \file OutlineListView.h + \ingroup interface + \ingroup libbe + \brief Provides the BOutlineListView class. +*/ + + +/*! + \class BOutlineListView + \ingroup interface + \ingroup libbe + \brief Expands upon BListView to display a hierarchical list of items. + + Items with subitems underneath them are called super items and are drawn + with a small arrow to the left of their label. The label faces right if + the item is collapsed and faces down if the item is expanded. + + An example of an outline list view looks like this: + + \image html BOutlineListView_example.png + + \see BListView for more info on how to use a list view, most of which also + applies to an outline list view. +*/ + + +/*! + \fn BOutlineListView::BOutlineListView(BRect frame, const char* name, + list_view_type type, uint32 resizingMode, uint32 flags) + \brief Creates a new BOutlineListView object. + + \param frame The \a frame rectangle to create the view in. + \param name The name of the view. + \param type Whether the list view supports a single selection or multiple + selections. + \param resizingMode The resizing mode flags. See BView for details. + \param flags The view flags. See BView for details. +*/ + + +/*! + \fn BOutlineListView::BOutlineListView(const char* name, + list_view_type type, uint32 flags) + \brief Creates a new BOutlineListView object suitable for use in a BLayout. + + \param name The name of the view. + \param type Whether the list view supports a single selection or multiple + selections. + \param flags The view flags. See BView for details. +*/ + + +/*! + \fn BOutlineListView::BOutlineListView(BMessage* archive) + \brief Creates a BOutlineListView object from the \a archive message. + + \param archive The message to create the object from. +*/ + + +/*! + \fn BOutlineListView::~BOutlineListView() + \brief Delete the outline BOutlineListView object and free the memory used + by it. + + This method does not free the attached list items. +*/ + + +/*! + \name Archiving +*/ + + +//! @{ + + +/*! + \fn BArchivable* BOutlineListView::Instantiate(BMessage* archive) + \brief Create a new BOutlineListView object from the message \a archive. + + \param archive The message to create the object from. +*/ + + +/*! + \fn status_t BOutlineListView::Archive(BMessage* archive, bool deep) const + \brief Archive the BOutlineListView object to a message. + + \param archive The message to archive the object to. + \param deep \c true to archive child views. +*/ + + +//! @} + + +/*! + \name Hook methods +*/ + + +//! @{ + + +/*! + \fn void BOutlineListView::AllAttached() + \brief Hook method called once all views are attached to the outline list + view. + + \see BView::AllAttached() +*/ + + +/*! + \fn void BOutlineListView::AllDetached() + \brief Hook method called once all views are detached from the outline list + view. + + \see BView::AllDetached() +*/ + + +/*! + \fn void BOutlineListView::DetachedFromWindow() + \brief Hook method that is called when the outline list view is removed from + the view hierarchy. + + \see BView::DetachedFromWindow() +*/ + + +/*! + \fn void BOutlineListView::FrameMoved(BPoint new_position) + \brief Hook method called when the outline list view is moved. + + \param new_position The list view's new position. + + \see BView::FrameMoved() +*/ + + +/*! + \fn void BOutlineListView::FrameResized(float width, float height) + \brief Hook method called when the outline list view is resized. + + \param width The new \a width of the view. + \param height The new \a height of the view. + + \see BView::FrameResized() +*/ + + +/*! + \fn void BOutlineListView::KeyDown(const char* bytes, int32 numBytes) + \brief Hook method that is called when a key is pressed while the view is + the focus view of the active window. + + Responds to arrow keys to provide the ability to navigate the outline list + or to expand or collapse sections of the outline. Inherits the keys + recognized by BListView. + + The following keys are used by the outline list view by default: + - Right Arrow Expands the selected item. + - Left Arrow Collapses the selected item. + + \param bytes The bytes of the key combination pressed. + \param numBytes The number of bytes in \a bytes. + + \see BListView::KeyDown() +*/ + + +/*! + \fn void BOutlineListView::MessageReceived(BMessage* message) + \brief Hook method called when a message is received by the outline list + view. + + \param message The message received by the view. + + \see BView::MessageReceived() +*/ + + +/*! + \fn void BOutlineListView::MouseDown(BPoint where) + \brief Hook method called when a mouse button is pressed while the cursor + is contained in the frame of the outline list view. + + Responds to mouse clicks expanding or collapsing sections of the outline + when the user clicks on a latch. + + \param where The point on the screen where to mouse pointer is when + the mouse button is pressed. + + \see BListView::MouseDown() +*/ + + +/*! + \fn void BOutlineListView::MouseUp(BPoint where) + \brief Hook method that is called when a mouse button is released while + the cursor is contained in the frame of the outline list view. + + \param where The location that the mouse button was released. + + \see BView::MouseUp() +*/ + + +//! @} + + +/*! + \name Add and remove item methods +*/ + + +//! @{ + + +/*! + \fn bool BOutlineListView::AddUnder(BListItem* item, BListItem* superItem) + \brief Adds the \a item one level deeper and immediately after \a superItem. + + \param item The \a item to add. + \param superItem The item to add under, if \c NULL adds to end. + + \return \c true if the \a item was added, \c false otherwise. +*/ + + +/*! + \fn bool BOutlineListView::AddItem(BListItem* item) + \brief Adds the \a item to the end of the list. + + \param item The \a item to add. + + \return \c true if the \a item was added, \c false otherwise. +*/ + + +/*! + \fn bool BOutlineListView::AddItem(BListItem* item, int32 fullListIndex) + \brief Adds the \a item at \a fullListIndex. + + \param item The \a item to add. + \param fullListIndex The index to add \a item at. + + \return \c true if the \a item was added, \c false otherwise. +*/ + + +/*! + \fn bool BOutlineListView::AddList(BList* newItems) + \brief Adds a list of items to the end of the list. + + \param newItems The list of items to add. + + \return \c true if the items was added, \c false otherwise. +*/ + + +/*! + \fn bool BOutlineListView::AddList(BList* newItems, int32 fullListIndex) + \brief Adds a list of items at \a fullListIndex + + \param newItems The list of items to add. + \param fullListIndex The index to add \a item at. + + \return \c true if the items was added, \c false otherwise. +*/ + + +/*! + \fn bool BOutlineListView::RemoveItem(BListItem* item) + \brief Removes the \a item from the list. + + \param item The \a item to remove. + + \return \c true if the \a item was removed, \c false otherwise. +*/ + + +/*! + \fn BListItem* BOutlineListView::RemoveItem(int32 fullListIndex) + \brief Removes the \a item located at \a fullListIndex from the list. + + \return A pointer to the BListItem removed. +*/ + + +/*! + \fn bool BOutlineListView::RemoveItems(int32 fullListIndex, int32 count) + \brief Removes \a count items starting at \a fullListIndex from the list. + + \return \c true if the items were removed, \c false otherwise. +*/ + + +//! @} + + +/*! + \name Full list methods + + These methods replicate similar methods in BListView except work on the + full list. +*/ + + +//! @{ + + +/*! + \fn BListItem* BOutlineListView::FullListItemAt(int32 fullListIndex) const + \brief Returns a pointer to the BListItem at \a fullListIndex. + + \return A pointer to the the BListItem at \a fullListIndex or \c NULL if not + found. + + \see BListView::ItemAt(int32 index) +*/ + + +/*! + \fn int32 BOutlineListView::FullListIndexOf(BPoint where) const + \brief Returns the full list index of the item at \a where. + + \return The index of the item at \a where or -1 if not found. + + \see BListView::IndexOf(BListItem* item) +*/ + + +/*! + \fn int32 BOutlineListView::FullListIndexOf(BListItem* item) const + \brief Returns the full list index of \a item. + + \return The index of the item at \a where or -1 if not found. + + \see BListView::IndexOf(BPoint point) +*/ + + +/*! + \fn BListItem* BOutlineListView::FullListFirstItem() const + \brief Returns a pointer to the first BListItem in the list. + + \return A pointer to the first item in the list or \c NULL there are no + items. + + \see BListView::FirstItem() +*/ + + +/*! + \fn BListItem* BOutlineListView::FullListLastItem() const + \brief Returns a pointer to the list BListItem in the list + + \return A pointer to the last item in the list or \c NULL there are no + items. + + \see BListView::LastItem() +*/ + + +/*! + \fn bool BOutlineListView::FullListHasItem(BListItem* item) const + \brief Returns whether or not the list contains the specified \a item. + + \param item The list item to check. + + \return \c true if \a item is in the list, \c false otherwise. + + \see BListView::HasItem(BListItem* item) +*/ + + +/*! + \fn int32 BOutlineListView::FullListCountItems() const + \brief Returns the number of items contained in the outline list view. + + \return The number of items. + + \see BListView::CountItems() +*/ + + +/*! + \fn int32 BOutlineListView::FullListCurrentSelection(int32 index) const + \brief Returns the index of a currently selected item relative to the passed + in \a index. + + \param index The \a index of the item to get relative to the selected item's + index. + + \see BListView::CurrentSelection(int32 index) +*/ + + +/*! + \fn void BOutlineListView::MakeEmpty() + \brief Empties the outline list view of all items. +*/ + + +/*! + \fn bool BOutlineListView::FullListIsEmpty() const + \brief Returns whether or not the outline list view is empty. + + \return \c true if the outline list view is empty, \c false otherwise. + + \see BListView::IsEmpty() +*/ + + +/*! + \fn void BOutlineListView::FullListDoForEach(bool(*func)(BListItem* item)) + \brief Calls the specified function on each item in the outline list. + + \param func The function to call on each item. + + \see BListView::DoForEach(bool (*func)(BListItem* item)) +*/ + + +/*! + \fn void BOutlineListView::FullListDoForEach(bool(*func)(BListItem* item, + void* arg), void* arg) + \brief Calls the specified function on each item in the outline list. + + \param func The function to call on each item. + \param arg The second argument of the function. + + \sa BListView::DoForEach(bool (*func)(BListItem* item, void* arg), + void* arg) +*/ + + +//! @} + + +/*! + \fn BListItem* BOutlineListView::Superitem(const BListItem* item) + \brief Returns a pointer to the item at one level above \a item. + + \return A pointer to the superitem of \a item or \c NULL if the \a item + is at the outermost level or not found. +*/ + + +/*! + \fn void BOutlineListView::Expand(BListItem* item) + \brief Expands the section referenced by \a item. +*/ + + +/*! + \fn void BOutlineListView::Collapse(BListItem* item) + \brief Collapses the section referenced by \a item. +*/ + + +/*! + \fn bool BOutlineListView::IsExpanded(int32 fullListIndex) + \brief Returns whether or not the section that the item at \a fullListIndex + is expanded or not. + + \return \c true if the section is expanded, \c false if it is collapsed. +*/ + + +/*! + \name Sort methods +*/ + + +//! @{ + + +/*! + \fn void BOutlineListView::FullListSortItems( + int (*compareFunc)(const BListItem* a, const BListItem* b)) + \brief Sort the items according the the passed in compare function. + + \param compareFunc The compare function to use to sort the items. + + \see BListView::SortItems(int (*cmp)(const void *, const void *)) +*/ + + +/*! + \fn void BOutlineListView::SortItemsUnder(BListItem* superItem, + bool oneLevelOnly, int (*compareFunc)(const BListItem* a, + const BListItem* b)) + \brief Sorts the items under \a superItem. + + \param superItem The base item. + \param oneLevelOnly if \c true, only items located one level under + superItem are considered. + \param compareFunc The compare function to use to sort the items. +*/ + + +//! @} + + +/*! + \fn int32 BOutlineListView::CountItemsUnder(BListItem* superItem, + bool oneLevelOnly) const + \brief Returns the number of items under \a superItem. + + \param superItem The base item. + \param oneLevelOnly if \c true, only items located one level under + superItem are considered. + + \return The number of items under \a superItem. +*/ + + +/*! + \fn BListItem* BOutlineListView::EachItemUnder(BListItem* superItem, + bool oneLevelOnly, BListItem* (*eachFunc)(BListItem* item, void* arg), + void* arg) + \brief Calls \a eachFunc for each item under \a superItem. + + \param superItem The base item. + \param oneLevelOnly if \c true, only items located one level under + superItem are considered. + \param eachFunc The function to call on each item. + \param arg The second argument of \a eachFunc. +*/ + + +/*! + \fn BListItem* BOutlineListView::ItemUnderAt(BListItem* superItem, + bool oneLevelOnly, int32 index) const + \brief Returns a pointer to the item at \a index under \a superItem. + + \note If \a oneLevelOnly is \a false, this method acts like + FullListItemAt() except the first item in the list is + considered to be \a superItem. + + \param superItem The base item. + \param oneLevelOnly if \c true, only items located one level under + superItem are considered. + \param index The index of the item to get. + + \return A pointer to the item at \a index under \a superItem or \c NULL + if not found. +*/ + + +/*! + \fn bool BOutlineListView::DoMiscellaneous(MiscCode code, MiscData* data) + \brief If \a code is \a B_SWAP_OP, swap the items in \a data, otherwise + pass the arguments to BListView::DoMiscellaneous(). + + \param code The action \a code to use. + \param data The \a data to act on. + + \see BListView::DoMiscellaneous() +*/ + + +/*! + \fn void BOutlineListView::ExpandOrCollapse(BListItem* item, bool expand) + \brief Toggle the expanded state of \a item. + + \param item The \a item to toggle. + \param expand If \c true, expand the \a item, if \c false, collapse the + \a item. +*/ + + +/*! + \fn BRect BOutlineListView::LatchRect(BRect itemRect, int32 level) const + \brief Used by derived classes to return the latch area. + + \param itemRect The area of the item to get the latch area of. + \param level The \a level of the item to get the latch area of. +*/ + + +/*! + \fn void BOutlineListView::DrawLatch(BRect itemRect, int32 level, + bool collapsed, bool highlighted, bool misTracked) + \brief Used by derived classes to draw the latch. + + \param itemRect The area of the item to get the latch area of, + this is passed to LatchRect() to get the latch area. + \param level The \a level of the item to get the latch area of, + also passed to LatchRect(). + \param collapsed \c true to draw the latch in a collapsed state, + \c false to draw the latch in an expanded state. + \param highlighted \c true to draw the latch in a selected state, + \c false to draw the latch in an unselected state. Unused + by the base class. + \param misTracked Unused by the base class. +*/ + + +/*! + \fn void BOutlineListView::DrawItem(BListItem* item, BRect itemRect, + bool complete) + \brief Used by derived classes to draw the \a item. + + \param item The \a item to draw. + \param itemRect The area of the \a item to draw. + \param complete Whether or not to draw the background in addition to the + contents. +*/ diff --git a/docs/user/interface/images/BOutlineListView_example.png b/docs/user/interface/images/BOutlineListView_example.png new file mode 100644 index 0000000000000000000000000000000000000000..2497ca4d361edb9112584fea5e4aa593d59c8c8f GIT binary patch literal 2775 zcmaJ@cU%+M7LK@ry9iilQbW*Hgk+KcVq%H`0%E`t*d_afUKcBVsfBXnO{ybyY>h&EaeO)JGzhS-z8TO7_3f-p(|-yej#aan;N9b^Sa zL+e2T47P9;$BQ9mc(~))d@hQm@v^-0ki`WgT~uC;L#ZP zmkR+!69(+Y)16(u#DZ2tM37i4zym;dcsMHD7R46^0vH?)2cWS47K?;DkRmBh%#t8^ zBFnD~&Y*}b>6@UO86!F7^Y^ZR%Emffecqbvq67z*#e16E+Q`{cJ7xP6y zd;#3a(;kI^d$8CXp33qW;o*UI?ux;7!1|c z(azS{WrID|j^g5kS#O8^igo6*!?++%{1qGU4NF0P7prOpt^kVc3<^1W!2lN_p9}w- zG@kQ)EzaNN`+^Plt`;2iyI24c1E@;-U#0$Pg8E1G`mJ%H#kbZ6c~HL#p~hZP)^rN` zDA3#8y{Px@-Rte`t*@_7OG_Ia9o5#>e*5;VP$(=ZDe?33i;j-Ibm{u6> zK_8ex)%Z^;_Ha_FOiqoY_wc)$3@QowJMrFQHATZeYBo8%%6dJEEZp#~!+Sp&(vWaA z6aS(#?+iP+Lz%yHFh~1pk|hupOnbQez4uaM(>VPteTywRsW;AF(6a*e!7iudmY*m; z;NP(LsY#Ij30=oymcc*R5p>G!(m6N!k1v9OhvV~C954vN--PSER?m2PW+DK{8#Vn3FtPcNaUJZ{DPK=#bCYaxc+GOoC^e zRkmL~N*?pu+SX0dE2*?ytov~lTEO_#VYa(em9dyjqiLxWCg z6w4 zE&ok!aY0$O>`78#C{6K!ZaJN9TC}# z`cY|5(z8`i&C-Bbf+9P=lD3XOYU6;&b)PTf}h;Re%j^Q6A=yl*L+reAyFihSf{ zWmx0YvE@z;9(7qG4YPlSRa@GqOp;g&kc4jniG~q}dT#QhCz(N;rH76TbsA1{ewS(i zvA$-3NdmR<;gl9IJP{aUyC1l`_SDO=o{n0!%|VkC z-&%G#u5^k}7-A-mdD{S<@tL8G05Pc-Q#D7`Ue0N2|4Dn3-1$C3+QHmNH*Fy?DtbYE z`r$<7t-`$4RD<$ImUWxVGo;|21ImTpRZ)b zdS~meObs=^vajQQPywZU=mgt_kjeBca7SWMO?KQ|gFot$pBL$MkFjo5L&Pd{h{E)xoYHmj z3bnT9c7aQIO9e7-h5NE7!$C;eP}JY#C)Pt7%{De$4>iW)Y|^{@;`Uq3Wqq2hqCIJ( zgm!alC%2aqHY=ixT}hVmnT1Sdwr_R7-uG@9K%#AW*K2lzd4J69l3p{xXADQyu#hXAfG%@N+wp?Jk1Xb?e2?h9=rIU6Vvl}s>p!T zyaFJ+uhdtc8czF=K1wrkt%ZLej2I<~e8_}sCGnWa!$BL>Qn^+nahGO{Fw`mCk+p2; z56KfNndLc3yiu;Z8Oo%_7op2sQvT$l49nsEnKh_ufWwLL5=M21kT zG7EmGstWN%7HeJ+<}#PY`|6MTE~*fi>JE0DKUlzZAYD$;0JM#Lb<*xH2xv3gJHn_! zO`EVI`l&Jd^V3Q_ T`ms;;RdNk)4tkp)cz)~$oC(HSwxuu$baljGVR`_c>_5A@* zqx{yw%rIo|LBn<()-*=X!PUt9^)k&l?MH)k4U%gKbx?6e8ic0V_pBQ~7R?_uh?uOv z+jf;@Fw-vA<<~E6RA;8&aXY$v8f{*Gy0$K2HRqWIQ9I%)6J24_lzIH*zzEaL=p#j5 z{da@rstdy6V;0~mH(lJ}b9J+pjXOU^D|ekR?6ppEN#^XX|2w&-d@Lo?tx3-?RYlVl ze3j`=uH}*s@9=MSPq)?L=;98Y(~+8t_m0x??vz-$#QHi=McEdKi0N$e(U1bHnf2=; zsEwe}nbqH8!+h1J&b`ijXPDif658HU{5UC9Pqs4YIH{d@Cev@5amV!Cf#*A=6kzv| z{;ycstE8wz2_}=R59-{x<@=&ny4{ literal 0 HcmV?d00001