CascadeDirBrowser Class Reference

a graphical directory-browsing class More...

#include <cascade/util/CascadeDirBrowser.h>

Inheritance diagram for CascadeDirBrowser:

List of all members.


Public Types
typedef void()	BrowseDirectoryCallback (const CascadeString &inPath, CallbackReason inReason, void *pClientData)
enum	CallbackReason { eOK, eCancel }
enum	SelectableObjectType { eFiles, eDirectories, eBoth }
Public Member Functions
	CascadeDirBrowser ()
virtual	~CascadeDirBrowser ()
virtual bool	BrowseDirectory (const CascadeString &inTitle, const CascadeString &inPath, const CascadeString &inRoot, const CascadeString &inName, CascadeFSObject::Selector inDirSelector, CascadeFSObject::Selector inFileSelector, SelectableObjectType inType, BrowseDirectoryCallback inCallback, void inClientData)
virtual void	OnPaint (CascadeBitmap &bitmap)
virtual void	OnMaterialize ()
virtual void	OnVanish ()
virtual bool	OnKeyDown (u32 nKey)
virtual void	OnSetFocus ()
virtual bool	OnNavKey (u32 nKey, CascadeWindow *&pProposedNewFocusWnd)
virtual bool	WillAcceptFocus ()
Protected Member Functions
void	Back ()
void	Top ()
bool	Setup (void)
void	SetupButton (CascadeButtonWidget &button, CascadeBitmap &normalBitmap, CascadeBitmap &highlightBitmap, CascadeBitmap &disabledBitmap, CascadeRect &rect, const char *text)
void	SetupDirButton (BrowserButton &button, CascadeBitmap &normalBitmap, CascadeBitmap &highlightBitmap)
void	SetupContents (void)
void	ScrollUp ()
void	ScrollDown ()
void	PaintContents (CascadeBitmap &inBitmap, CascadeRect &inRect)
bool	SetDirectory (const CascadeString &inPath)
void	ClearContents ()
Static Protected Member Functions
static void	ButtonCallback (const CascadeButtonWidget pButton, const CascadeButtonWidget::State &newState, void pClientData)
static void	DirButtonCallback (const CascadeButtonWidget pButton, const CascadeButtonWidget::State &newState, void pClientData)
Protected Attributes
BrowseDirectoryCallback *	mCallbackFunction
void *	mCallbackClientData
CallbackReason	mReason
CascadeString	mTitle
CascadeFSObject::Selector *	mFileSelector
CascadeFSObject::Selector *	mDirSelector
SelectableObjectType	mType
CascadeDirectory	mRootDirectory
CascadeDirectory	mCurDirectory
CascadeString	mCurSelection
CascadeString	mName
CascadeTemplateArray< CascadeFSObject * > *	mContents
u32	mFileCount
u32	mDirCount
bool	mFileSelected
u32	mFirstVisibleIdx
u32	mVisibleButtonCount
CascadeFont	mPathFont
CascadeFont	mContentsHeadingFont
CascadeFont	mContentsFont
CascadeFont	mListFont
CascadeBitmap	mBackground
CascadeBitmap	mButtonNormal
CascadeBitmap	mButtonHighlight
CascadeBitmap	mButtonDisabled
CascadeBitmap	mTopButtonNormal
CascadeBitmap	mTopButtonHighlight
CascadeBitmap	mBackButtonNormal
CascadeBitmap	mBackButtonHighlight
CascadeBitmap	mDirectoryButtonNorm
CascadeBitmap	mDirectoryButtonHi
CascadeBitmap	mFileButtonUnselectNorm
CascadeBitmap	mFileButtonUnselectHi
CascadeBitmap	mScrollUpArrow
CascadeBitmap	mScrollDownArrow
CascadeButtonWidget	mTopButton
CascadeButtonWidget	mBackButton
CascadeButtonWidget	mSelectButton
CascadeButtonWidget	mCancelButton
BrowserButton **	mDirButtons
bool	mbSetup
CascadeButtonWidget *	mFocusLeftButton
CascadeButtonWidget *	mFocusRightButton
CascadeButtonWidget *	mFocusButton
Classes
class	BrowserButton

Detailed Description

a graphical directory-browsing class

Skip the description

CascadeDirBrowser is a sub-class of CascadeWindow, which allows the user to navigate a filesystem hierarchy and select a file or folder.

Two independent selector objects are passed in. These are used to determine what items to [i]display[/i] in the dialog. Additionally, the inType parameter is used to specify which displayed items are actually selectable.

Directories always have a button displayed next to them, to allow navigation into the hierarchy. If you wish to constrain the dialog to a particular directory, pass a selector that will not select any directories.

Files only have a button next to them if files are selectable. Otherwise, a "focus" indicator is shown next to them to facilitate list scrolling, but the file can't be selected.

In this fashion, for example, the caller may specify that all directories are to be shown, but only files are selectable. Or, perhaps a directory is what is to be selected, but it is desired to show the directory's contents to allow the user to ensure that they have chosen the correct directory.

Navigation is constrained so that it cannot proceed up the path past a specified root. Also, the filesystem location of a given path can be obscured by specifying an alternate name for the root (e.g. if the root is "/mnt/flash1" and the name is "Compact Flash", then the user will see "Compact Flash/Images" instead of "/mnt/flash1/Images"

class CascadeDirBrowser

Member Typedef Documentation

typedef void() CascadeDirBrowser::BrowseDirectoryCallback(const CascadeString &inPath, CallbackReason inReason, void *pClientData)

dialog-finished callback function
Supply a callback function matching this signature to RegisterCallback. The function will be called when the dialog exits, whether with a new choice, or because the user canceled.

Parameters:

inPath the new path chosen, if inReason is eOK

inReason the result of the dialog. eOK means that the user chose a new directory. eCancel means that they exited without choosing a new directory.

pClientData the client data pointer supplied in RegisterCallback

Member Enumeration Documentation

enum CascadeDirBrowser::CallbackReason

Enumeration values:

eOK

eCancel

enum CascadeDirBrowser::SelectableObjectType

Enumeration values:

eFiles

eDirectories

eBoth

Constructor & Destructor Documentation

CascadeDirBrowser::CascadeDirBrowser ( )

default constructor
Creates a CascadeDirBrowser object for later use. You must call RegisterCallback and then BrowseDirectory (in that order) to pop up the dialog.

virtual CascadeDirBrowser::~CascadeDirBrowser ( ) [virtual]

destructor
Destructor

Member Function Documentation

void CascadeDirBrowser::Back ( ) [protected]

virtual bool CascadeDirBrowser::BrowseDirectory ( const CascadeString & inTitle,

const CascadeString & inPath,

const CascadeString & inRoot,

const CascadeString & inName,

CascadeFSObject::Selector * inDirSelector,

CascadeFSObject::Selector * inFileSelector,

SelectableObjectType inType,

BrowseDirectoryCallback * inCallback,

void * inClientData

) [virtual]

Opens the directory browser.
Opens the directory browser, starting at inPath. Browser will not allow traversal above the specified root. Specify an alternate "human-readable" name in inName for the root, if you wish the path to be more user friendly. Just pass the root string again if you want to see a full path. Pass "/" for inRoot if you don't want to limit the browser.
A selector is always required for the directory argument, because the browser needs to know which sub-directories to display. The file selector is optional if inType is eDirectories, and is used to display the un-selectable directory contents. If eType is eBoth or eFiles, the file selector is required.
inType determines whether the browser is to allow selection of directories or files or both.
inCallback is required, but inClientData can be NULL if your callback does not need any other information.

Parameters:

inTitle the title displayed at the top of the dialog.

inPath the starting path.

inRoot the "root" of the starting path (it must be part of the supplied path) -- the browser will not allow directory traversal above this point in the path.

inName the name to display in place of the root portion of the directory, e.g. "Compact Flash/Images" rather than "/mnt/flash1/Images" Just pass the same string as inRoot if you want to show the "real" path.

inDirSelector a CascadeFSObject::Selector object to use in determining which directories to display. Required. The object is deleted when the browser is closed, so be sure to allocate on the heap with new

inFileSelector a CascadeFSObject::Selector object to use in determining which files to display. May be NULL if inType is eDirectories. May also be provided even if inType is eDirectories if it is desired to show the contents of directories to aid in their identification. The object is deleted when the browser is closed, so be sure to allocate on the heap with new

inType specifies whether files, directories or both are selectable.

inCallback the callback function to execute when the dialog is closed for any reason. Required.

inClientData pointer which is passed to the callback function. May be NULL.

Returns:
if dialog opening was successful. May return false on error conditions, or if the specified directories don't exist.

static void CascadeDirBrowser::ButtonCallback ( const CascadeButtonWidget * pButton,

const CascadeButtonWidget::State & newState,

void * pClientData

) [static, protected]

void CascadeDirBrowser::ClearContents ( ) [protected]

static void CascadeDirBrowser::DirButtonCallback ( const CascadeButtonWidget * pButton,

const CascadeButtonWidget::State & newState,

void * pClientData

) [static, protected]

virtual bool CascadeDirBrowser::OnKeyDown ( u32 nKey ) [virtual]

called to handle a key down CK_KEY message
OnKeyDown() gets called to handle a key down message. return true to indicate you have processed the message; false to allow the message to continue to be dispatched. NOTE that navigation keys (CK_NORTH, etc.) do not get dispatched to OnKeyDown(), they get dispatched to OnNavKey().
Parameters:

nKey the CK_KEY being notified

Returns:
true to prevent further message processing, false to allow it

See also:
OnKeyUp()
CascadeApp

Reimplemented from CascadeWindow.

virtual void CascadeDirBrowser::OnMaterialize ( ) [virtual]

notifies the window when it has been materialized on screen
OnMaterialize() gets called when the window has been materialized, before it has been painted.
See also:
Materialize(), Vanish()
OnVanish()

Reimplemented from CascadeWindow.

virtual bool CascadeDirBrowser::OnNavKey ( u32 nKey,

CascadeWindow *& pProposedNewFocusWnd

) [virtual]

called to handle a navigation key message
OnNavKey() gets called to handle a navigation key message. pProposedNewFocusWnd is the proposed new focus window. Clients who override this function may examine pProposedNewFocusWnd and change it if they want. OnNavKey() will be successively be called on a window and its parents until someone returns true, indicating they wish message dispatch to stop. At that point the pProposedNewFocusWnd (if non-NULL) will be set as the new focus window. The base class implementation returns false to allow its parent a chance to change the pProposedNewFocusWnd. If at the end of this business, pProposedNewFocusWnd doesn't point to a new focus window, then the focus will not change and the nav key will get dispatched to your CascadeApp's OnKeyDown() handler.
Parameters:

nKey the navigation key being processed

pProposedNewFocusWnd a settable pointer to the proposed new focus window

Returns:
true to prevent further message processing, false to allow it

See also:
CascadeApp

Reimplemented from CascadeWindow.

virtual void CascadeDirBrowser::OnPaint ( CascadeBitmap & bitmap ) [virtual]

Called to instruct this window to paint
OnPaint() is called by the Cascade Windowing system to instruct your window to paint (on the bitmap passed in). Higher system performance will result if you manually clip your painting to the bitmap's clipRect (bitmap.GetClipRect()), though this is not required. It IS required to manually clip your painting to the window's absolute rect (since the graphics library doesn't yet support clipping). OnPaint() will only be called by the Cascade windowing system if some portion of the window's absolute rect intersects with the bitmap's clipRect. clients can manually call OnPaint to instruct the window to paint to an arbitrary bitmap outside of the context of the Cascade windowing system. Note that OnPaint() is a paint handling function for a single window. To cause a window and all of its child windows to paint, call PaintTree() instead.
Note:
Windows are themselves responsible for determining if they are the active window with input focus and rendering appropriately.

Parameters:

bitmap The bitmap to paint onto

See also:
OnPaint()
CascadeBitmap

Reimplemented from CascadeWindow.

virtual void CascadeDirBrowser::OnSetFocus ( ) [virtual]

notifies the window when it has gained focus
OnSetFocus() gets called when the window has gained focus. The window will be redrawn automatically (after OnSetFocus()). Clients should not redraw in OnSetFocus() but they may update member variables if desired before painting occurs.
See also:
SetFocus(), ClearFocus()
OnClearFocus()

Reimplemented from CascadeWindow.

virtual void CascadeDirBrowser::OnVanish ( ) [virtual]

notifies the window that it has vanished from the screen
OnVanish() gets called when the window has vanished, before the screen has been updated.
Reimplemented from CascadeWindow.

void CascadeDirBrowser::PaintContents ( CascadeBitmap & inBitmap,

CascadeRect & inRect

) [protected]

void CascadeDirBrowser::ScrollDown ( ) [protected]

void CascadeDirBrowser::ScrollUp ( ) [protected]

bool CascadeDirBrowser::SetDirectory ( const CascadeString & inPath ) [protected]

bool CascadeDirBrowser::Setup ( void ) [protected]

void CascadeDirBrowser::SetupButton ( CascadeButtonWidget & button,

CascadeBitmap & normalBitmap,

CascadeBitmap & highlightBitmap,

CascadeBitmap & disabledBitmap,

CascadeRect & rect,

const char * text

) [protected]

void CascadeDirBrowser::SetupContents ( void ) [protected]

void CascadeDirBrowser::SetupDirButton ( BrowserButton & button,

CascadeBitmap & normalBitmap,

CascadeBitmap & highlightBitmap

) [protected]

void CascadeDirBrowser::Top ( ) [protected]

virtual bool CascadeDirBrowser::WillAcceptFocus ( ) [inline, virtual]

called to ask the window if it will accept focus
WillAcceptFocus() is called during navigation allow the window to indicate whether or not it will accept the focus at the current point in time.
Returns:
whether or not the window will accept focus at this time

Reimplemented from CascadeWindow.