You.i Engine
CYIStreamer Class Referenceabstract

Detailed Description

A class that implements a scene node streamer.

The streamer class manages a list of streamable items. When these items are in the 'streaming region', they get streamed in. When these items are out of the 'streaming region', they get streamed out. The streaming region (and whether a given item is within the streaming region or not) is defined by the subclass implementation of CYIStreamer.

The streamable items are created automatically when an instance of CYINodeAdapter is assigned to the streamer. New items are also created (or removed) as needed when the adapter notifies that new items have been added. If the associated adapter is removed from the streamer, all existing streamable items are removed.

When a streamable item is streamed in, the associated CYINodeAdapter instance is used to create a scene node for it. When a streamable item is streamed out, that scene node is released back to the associated CYINodeAdapter instance.

In order to use a CYIStreamer object, a subclass must be made that implements the pure virtual functions. These functions handle the actual attachment of scene nodes to a scene tree. Typically, the class that implements a streamer would be a subclass of CYISceneNode. The subclass of CYIStreamer must call CYIStreamer::Init to initialize the streamer.

Note
Indices used in the streamer are 0-based and without gaps. Subclasses of the streamer may remap those indices to a different range. For example, a CYISceneView subclass of this streamer class may insert items within its children list, but offset them by a specific amount to account for a header. A CYISceneView subclass may also 'reverse' the order of items within its children list. Subclasses of this streamer must ensure that the indices provided by streamer functions are remapped to the indices used by the streamer subclass.

#include <streamer/YiStreamer.h>

Inheritance diagram for CYIStreamer:

Public Member Functions

 CYIStreamer ()
 
virtual ~CYIStreamer ()
 
void SetAdapter (std::unique_ptr< CYINodeAdapter > pAdapter)
 
const CYINodeAdapterGetAdapter () const
 
CYINodeAdapterGetAdapter ()
 
bool RequestFocusOnItem (size_t index, CYIFocus::Direction direction=CYIFocus::Direction::Forward, CYIFocus::FocusRootRule focusRootRule=CYIFocus::FocusRootRule::DescendantsUpdateContext, const CYIAABB &previousFocusRect=CYIAABB())
 
bool IsStreamedIn (size_t index) const
 
CYISceneNodeGetStreamedNode (size_t index) const
 
size_t GetItemIndex (CYISceneNode *pStreamableItem) const
 

Protected Member Functions

void Init (CYISceneManager *pSceneManager)
 
void UpdateStreamedStateOfAllItems ()
 
virtual void StreamedIn (size_t index, CYISceneNode *pStreamedItem)
 
virtual void OnStreamedIn (size_t index, CYISceneNode *pStreamedItem)
 
virtual void StreamedOut (size_t index, CYISceneNode *pStreamedItem)
 
virtual void OnStreamedOut (size_t index, CYISceneNode *pStreamedItem)
 
virtual void InsertItem (size_t index, std::unique_ptr< CYISceneNode > pItem)=0
 
virtual std::unique_ptr< CYISceneNodeRemoveItem (size_t index, CYISceneNode *pItem)=0
 
virtual void ReorderItem (size_t fromIndex, size_t toIndex, CYISceneNode *pItem)=0
 
virtual bool IsItemInStreamingRegion (CYISceneNode *pItem) const =0
 
virtual CYISceneNodeGetItem (size_t index) const =0
 
virtual bool CanBeStreamedOut (size_t index, CYISceneNode *pNode) const =0
 
virtual void OnFocusGainedForItem (size_t index)
 
virtual void FocusGainedForItem (size_t index)
 
virtual void OnFocusLostForItem (size_t index)
 
virtual void FocusLostForItem (size_t index)
 

Friends

class CYIStreamerSlots
 
class CYIStreamableView
 

Constructor & Destructor Documentation

◆ CYIStreamer()

CYIStreamer::CYIStreamer ( )

◆ ~CYIStreamer()

virtual CYIStreamer::~CYIStreamer ( )
virtual

Member Function Documentation

◆ CanBeStreamedOut()

virtual bool CYIStreamer::CanBeStreamedOut ( size_t  index,
CYISceneNode pNode 
) const
protectedpure virtual

Checks if the streamable item at index index can be streamed out. The implementation may require some nodes to remain streamed in, even if the node is outside of the streaming region.

◆ FocusGainedForItem()

virtual void CYIStreamer::FocusGainedForItem ( size_t  index)
protectedvirtual

A function called when focus enters the tree rooted at the item at index index.

Warning
Overrides must call the base class implementation.
See also
OnFocusGainedForItem

Reimplemented in CYIListView.

◆ FocusLostForItem()

virtual void CYIStreamer::FocusLostForItem ( size_t  index)
protectedvirtual

A function called when focus leaves the tree rooted at the item at index index.

Warning
Overrides must call the base class implementation.
See also
OnFocusLostForItem

Reimplemented in CYIListView.

◆ GetAdapter() [1/2]

const CYINodeAdapter* CYIStreamer::GetAdapter ( ) const
See also
SetAdapter

◆ GetAdapter() [2/2]

CYINodeAdapter* CYIStreamer::GetAdapter ( )
See also
SetAdapter

◆ GetItem()

virtual CYISceneNode* CYIStreamer::GetItem ( size_t  index) const
protectedpure virtual

Fetches and returns the streamable item at index index.

Note
See CYIStreamer for details on item indices.

◆ GetItemIndex()

size_t CYIStreamer::GetItemIndex ( CYISceneNode pStreamableItem) const

Returns the index of the streamable item pStreamableItem. If pStreamableItem is not a streamable item, std::numeric_limits<uint32_t>::max() is returned.

◆ GetStreamedNode()

CYISceneNode* CYIStreamer::GetStreamedNode ( size_t  index) const

Returns the streamed node for index index. Returns nullptr if the item at index index is not currently streamed in, or if index is out-of-bounds.

◆ Init()

void CYIStreamer::Init ( CYISceneManager pSceneManager)
protected

Initializes this streamer using the scene manager pSceneManager.

Note
This function must be called by implementations of CYIStreamer.

◆ InsertItem()

virtual void CYIStreamer::InsertItem ( size_t  index,
std::unique_ptr< CYISceneNode pItem 
)
protectedpure virtual

Inserts the streamable item pItem at index index.

Note
See CYIStreamer for details on item indices.

◆ IsItemInStreamingRegion()

virtual bool CYIStreamer::IsItemInStreamingRegion ( CYISceneNode pItem) const
protectedpure virtual

Checks if the streamable item pItem is currently in the streaming region.

◆ IsStreamedIn()

bool CYIStreamer::IsStreamedIn ( size_t  index) const

Returns true if the item at index index is currently streamed in, false otherwise. false is also returned if index is out-of-bounds.

◆ OnFocusGainedForItem()

virtual void CYIStreamer::OnFocusGainedForItem ( size_t  index)
protectedvirtual

A function called when focus enters the tree rooted at the item at index index.

Reimplemented in CYIListView.

◆ OnFocusLostForItem()

virtual void CYIStreamer::OnFocusLostForItem ( size_t  index)
protectedvirtual

A function called when focus leaves the tree rooted at the item at index index.

Reimplemented in CYIListView.

◆ OnStreamedIn()

virtual void CYIStreamer::OnStreamedIn ( size_t  index,
CYISceneNode pStreamedItem 
)
protectedvirtual

A function called when the item at index index is streamed in. The streamed node (as provided by the associated adapter) is provided as pStreamedItem. This function is called after the item has been attached to the scene tree. Subclasses can override this function to perform post-streaming logic.

Note
In some streamer implementations, the position of the streamed items is not set until later in the frame (e.g. after the layout pass). This function being called is only an indication that a new node has been attached to the scene tree.

Reimplemented in CYIListView.

◆ OnStreamedOut()

virtual void CYIStreamer::OnStreamedOut ( size_t  index,
CYISceneNode pStreamedItem 
)
protectedvirtual

A function called when the item at index index is streamed out. The streamed node (as provided by the associated adapter) is provided as pStreamedItem. This function is called before the item has been detached from the scene tree. Subclasses can override this function to perform post-streaming logic.

Reimplemented in CYIListView.

◆ RemoveItem()

virtual std::unique_ptr<CYISceneNode> CYIStreamer::RemoveItem ( size_t  index,
CYISceneNode pItem 
)
protectedpure virtual

Removes the streamable item pItem from the CYIStreamer implementation. The item pItem is expected to be at index index.

Warning
The item pItem must not be deleted.
Note
See CYIStreamer for details on item indices.

◆ ReorderItem()

virtual void CYIStreamer::ReorderItem ( size_t  fromIndex,
size_t  toIndex,
CYISceneNode pItem 
)
protectedpure virtual

Moves the streamable item pItem from index fromIndex to index toIndex.

Note
The new index of the item assumes that the item has been removed from the items list. For example, if the items list contains 'A, B, C, D' and 'ReorderItem(pNode, 0, 1)' is called, the new items list would be 'B, A, C, D'.
See CYIStreamer for details on item indices.

◆ RequestFocusOnItem()

bool CYIStreamer::RequestFocusOnItem ( size_t  index,
CYIFocus::Direction  direction = CYIFocus::Direction::Forward,
CYIFocus::FocusRootRule  focusRootRule = CYIFocus::FocusRootRule::DescendantsUpdateContext,
const CYIAABB previousFocusRect = CYIAABB() 
)

Assigns focus within the streamable item at index. Returns false if index does not represent a streamable item or the streamable item at index does not contain a focusable view.

See also
CYISceneView::RequestFocus

◆ SetAdapter()

void CYIStreamer::SetAdapter ( std::unique_ptr< CYINodeAdapter pAdapter)

Sets an adapter for use with this streamer.

When a new adapter is set, n new items are created in the streamer (where n matches the value returned by the adapter's GetItemsCount() function).

Note
If an adapter was already set on the streamer, all of the streamer items will be streamed out and removed, and the old adapter will be deleted.

◆ StreamedIn()

virtual void CYIStreamer::StreamedIn ( size_t  index,
CYISceneNode pStreamedItem 
)
protectedvirtual

A function called when the item at index index is streamed in. The streamed node (as provided by the associated adapter) is provided as pStreamedItem. This function is called after the item has been attached to the scene tree. Subclasses can override this function to perform post-streaming logic.

Note
In some streamer implementations, the position of the streamed items is not set until later in the frame (e.g. after the layout pass). This function being called is only an indication that a new node has been attached to the scene tree.
Warning
Overrides must call the base class implementation.
See also
OnStreamedIn()

◆ StreamedOut()

virtual void CYIStreamer::StreamedOut ( size_t  index,
CYISceneNode pStreamedItem 
)
protectedvirtual

A function called when the item at index index is streamed out. The streamed node (as provided by the associated adapter) is provided as pStreamedItem. This function is called before the item has been detached from the scene tree. Subclasses can override this function to perform post-streaming logic.

Warning
Overrides must call the base class implementation.
See also
OnStreamedOut()

◆ UpdateStreamedStateOfAllItems()

void CYIStreamer::UpdateStreamedStateOfAllItems ( )
protected

Causes the streamer to re-check the streamed state of all exiting items. Items that are now in the streaming region will be streamed in, and items that are no longer in the streaming region will be streamed out.

Friends And Related Function Documentation

◆ CYIStreamableView

friend class CYIStreamableView
friend

◆ CYIStreamerSlots

friend class CYIStreamerSlots
friend

The documentation for this class was generated from the following file: