IlvFileBrowser Class Reference

Dialog class. More...

#include <ilviews/gadgets/fbrowser.h>

List of all members.

Public Member Functions
	IlvFileBrowser (IlvDisplay *display, IlvSystemView transientFor, const char *dir=0, IlInt nb=0, const char *const *filters=0, const char *const *messages=0, IlvFileBrowserOption useSystemDlg=IlvUseDefault)
	Constructor.
void	ensureInScreen (IlvPos xMargin=0, IlvPos yMargin=0)
	Ensures that the file browser remains visible.
const char *	get ()
	Displays the file browser as a modal dialog and returns a string.
const char *	getDirectory () const
	Returns the directory part of the selected path.
IlvDisplay *	getDisplay () const
	Returns the display used to create the file browser.
const char *	getFileName () const
	Returns the file name part of the selected path.
IlInt	getIndex () const
	Returns the index of the default filter and the corresponding message.
IlInt	getIndexFromFilter (const char *filter) const
	Returns the index of a given filter.
IlInt	getIndexFromMessage (const char *message) const
	Returns the index of a given message.
IlvFileBrowserOption	getOption () const
	Returns the current option.
const char *	getPathName () const
	Returns the full name of the selected path.
const char *	getTitle () const
	Returns the title of the dialog.
IlvFileSelectorType	getType () const
	Returns the current type of the dialog.
void	moveToMouse (IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue)
	Moves the file browser relative to the location of the mouse.
void	moveToScreen (IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue)
	Moves the file browser relative to the root window.
void	moveToView (IlvView *view, IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue)
	Moves the file browser relative to another view.
void	setDirectory (const char *dir)
	Sets the directory to be browsed.
void	setFileName (const char *filename)
	Sets the default file name.
void	setIndex (IlInt index)
	Sets the index of the default filter and the corresponding message.
void	setOption (IlvFileBrowserOption option)
	Sets the current option.
void	setPathName (const char *path)
	Sets the directory to be browsed and the default file name.
IlInt	setPatterns (IlInt count, const char *const *filters, const char *const *messages)
	Initializes the filters and the related messages.
void	setTitle (const char *title)
	Sets the title of the dialog.
void	setType (IlvFileSelectorType t)
	Specifies whether this file browser must find a file that already exists.
virtual void	show ()
	Displays the file browser as a modal dialog.
Static Public Member Functions
static IlvFileBrowserOption	GetInitOption ()
	Returns the value read from the resources or environment variables, or the value overridden by SetInitOption.
static void	SetInitOption (IlvFileBrowserOption option)
	Overrides the resources or environment variables set for the current program.

---

Detailed Description

Dialog class.

Library: ilvadvgdt

The IlvFileBrowser class allows you to dynamically specify which file selector to use from IlvFileSelector (when available) or IlvFileChooser, through a unique programming interface.

You can select a file browser in code in two ways: either in the IlvFileBrowser constructor, or with the setOption member function. You can also select a file browser at run time using the ILVFILEBROWSEROPTIONS environment variable or resource. The possible values for this environment variable are UseDefault, UseAlwaysSystemDialog or UseAlwaysViewsDialog. For details, see the IlvFileBrowserOption enumeration.

See also:

IlvFileSelector, IlvFileChooser, IlvFileBrowserOption.

---

Constructor & Destructor Documentation

IlvFileBrowser::IlvFileBrowser	(	IlvDisplay *	display,
		IlvSystemView	transientFor,
		const char *	dir = 0,
		IlInt	nb = 0,
		const char *const *	filters = 0,
		const char *const *	messages = 0,
		IlvFileBrowserOption	useSystemDlg = IlvUseDefault
	)

Constructor.

Initializes a new instance of the IlvFileBrowser class that will display either the system dialog or the Rogue Wave Views built-in dialog, according to the parameter useSystemDlg.

Parameters:

	display	The connection to the display.
	transientFor	The system view for which the dialog is transient (see IlvView).
	dir	The directory to be browsed.
	count	The numbers of filters and related messages specified by the filters and messages parameters, respectively.
	filters	An array of strings representing the possible filters.
	messages	An array of strings representing the messages that describe the filters.
	useSystemDlg	A value specifying which dialog will be used. For details, see IlvFileBrowserOption.

---

Member Function Documentation

void IlvFileBrowser::ensureInScreen	(	IlvPos	xMargin = 0,
		IlvPos	yMargin = 0
	)

Ensures that the file browser remains visible.

This function moves the file browser so that it remains visible on the screen. If the file browser is higher than the screen, it will not move in the y direction. If the file browser is wider than the screen, it will not move in the x direction. xMargin and yMargin define margin distances that the file browser location must respect, as if the screen were 2*xMargin pixels less wide, and 2*yMargin pixels less high.
If the file browser is already entirely visible on the screen with the margins respected, this function does nothing.

Parameters:

	xMargin	The horizontal margin.
	yMargin	The vertical margin.

const char* IlvFileBrowser::get

(

)

Displays the file browser as a modal dialog and returns a string.

Returns:

The full path name selected or 0 if the dialog was canceled. This string must never be deleted or modified.

See also:

show

const char* IlvFileBrowser::getDirectory

(

)

const

Returns the directory part of the selected path.

Returns:

The directory part of the selected path (with the device if relevant). You must not delete or modify the string returned by this member function.

See also:

setDirectory

IlvDisplay* IlvFileBrowser::getDisplay

(

)

const

Returns the display used to create the file browser.

Returns:

The display used to create the file browser.

const char* IlvFileBrowser::getFileName

(

)

const

Returns the file name part of the selected path.

Returns:

The file name part of the selected path (with the extension if relevant). You must not delete or modify the string returned by this member function.

See also:

setFileName

IlInt IlvFileBrowser::getIndex

(

)

const

Returns the index of the default filter and the corresponding message.

Returns:

The index of the default filter and the corresponding message.

IlInt IlvFileBrowser::getIndexFromFilter

(

const char *

filter

)

const

Returns the index of a given filter.

Parameters:

filter

The filter to be retrieved.

Returns:

The index of filter in the list of filters stored in the IlvFileBrowser. It returns -1 if filter was not found.

See also:

getIndexFromMessage.

IlInt IlvFileBrowser::getIndexFromMessage

(

const char *

message

)

const

Returns the index of a given message.

Parameters:

message

The message to be retrieved.

Returns:

The index of message in the list of messages stored in the IlvFileBrowser. It returns -1 if message was not found.

See also:

getIndexFromFilter

static IlvFileBrowserOption IlvFileBrowser::GetInitOption

(

)

[static]

Returns the value read from the resources or environment variables, or the value overridden by SetInitOption.

Returns:

The value read from the resources or environment variables, or overridden by SetInitOption.

See also:

SetInitOption

IlvFileBrowserOption IlvFileBrowser::getOption

(

)

const

Returns the current option.

Returns:

The current option.

See also:

IlvFileBrowserOption.

const char* IlvFileBrowser::getPathName

(

)

const

Returns the full name of the selected path.

Returns:

The full name of the selected path. You must not delete or modify the string returned by this member function.

See also:

setPathName.

const char* IlvFileBrowser::getTitle

(

)

const

Returns the title of the dialog.

Returns:

The title of the dialog. You must not delete or modify the string returned by this member function.

See also:

setTitle

IlvFileSelectorType IlvFileBrowser::getType

(

)

const

Returns the current type of the dialog.

Returns:

The current type of the dialog.

See also:

setType.

void IlvFileBrowser::moveToMouse	(	IlvDirection	justification = IlvCenter,
		IlvPos	dx = 0,
		IlvPos	dy = 0,
		IlBoolean	ensureInScreen = IlTrue
	)

Moves the file browser relative to the location of the mouse.

This function moves the file browser so that the point indicated by justification is moved to the pointing device, with an offset of dx and dy.

Parameters:

	justification	Specifies how the new location of this file browser is calculated: IlvCenter: the center of the file browser; IlvTop: the middle of the top side of the file browser; IlvBottom: the middle of the bottom side of the file browser; IlvLeft: the middle of the left side of the file browser; IlvRight: the middle of the right side of the file browser; IlvTopLeft: the top left corner of the file browser; IlvTopRight: the top right corner of the file browser; IlvBottomLeft: the bottom left corner of the file browser; IlvBottomRight: the bottom right corner of the file browser;
	dx	The horizontal offset that is applied.
	dy	The vertical offset that is applied.
	ensureInScreen	If this Boolean value is not specified or set to IlTrue, the file browser will remain entirely within the screen, by calling ensureInScreen.

void IlvFileBrowser::moveToScreen	(	IlvDirection	justification = IlvCenter,
		IlvPos	dx = 0,
		IlvPos	dy = 0,
		IlBoolean	ensureInScreen = IlTrue
	)

Moves the file browser relative to the root window.

This function moves the file browser to the position indicated by justification, relative to the entire screen, with an offset of dx and dy.

Parameters:

	justification	Specifies how the new location of the file browser is calculated: IlvCenter: the center of the file browser is moved to the center of the screen. IlvTop: the top of the file browser is moved to the top of the screen. IlvBottom: the bottom side of the file browser is moved to the bottom of the screen. IlvLeft: the left side of the file browser is moved to the left side of the screen. IlvRight: the right side of the file browser is moved to the right side of the screen. IlvTopLeft: the top left corner of the file browser is moved to the top left corner of the screen. IlvTopRight: the top right corner of the file browser is moved to the top right corner of the screen. IlvBottomLeft: the bottom left corner of the file browser is moved to the bottom left corner of the screen. IlvBottomRight: the bottom right corner of the file browser is moved to the bottom right corner of the screen.
	dx	The horizontal offset that is applied.
	dy	The vertical offset that is applied.
	ensureInScreen	If this Boolean value is not specified or set to IlTrue, the file browser will remain entirely within the screen, by calling ensureInScreen.

void IlvFileBrowser::moveToView	(	IlvView *	view,
		IlvDirection	justification = IlvCenter,
		IlvPos	dx = 0,
		IlvPos	dy = 0,
		IlBoolean	ensureInScreen = IlTrue
	)

Moves the file browser relative to another view.

This function moves the file browser to the position indicated by justification, relative to the position and size of view, which must be another top view, with an offset of dx and dy.

Parameters:

	view	The reference view.
	justification	Specifies how the new location of this file browser is calculated. Valid values for this parameter are: IlvCenter: the center of the file browser is moved to the center of view. IlvTop: the bottom of the file browser is moved to the top of view. IlvBottom: the top of the file browser is moved to the bottom of view. IlvLeft: the right side of the file browser is moved to the left side of view. IlvRight: the left side of the file browser is moved to the right side of view. IlvTopLeft: the bottom right corner of the file browser is moved to the top left corner of view. IlvTopRight: the bottom left corner of the file browser is moved to the top right corner of view. IlvBottomLeft: the top right corner of the file browser is moved to the bottom left corner of view. IlvBottomRight: the top left corner of the file browser is moved to the bottom right corner of view.
	dx	The horizontal offset that is applied.
	dy	The vertical offset that is applied.
	ensureInScreen	If this Boolean value is not specified or set to IlTrue, the file browser will remain entirely within the screen, by calling ensureInScreen.

void IlvFileBrowser::setDirectory

(

const char *

dir

)

Sets the directory to be browsed.

Parameters:

dir

The directory to be browsed.

void IlvFileBrowser::setFileName

(

const char *

filename

)

Sets the default file name.

Parameters:

filename

The default file name.

void IlvFileBrowser::setIndex

(

IlInt

index

)

Sets the index of the default filter and the corresponding message.

Parameters:

index

The index of the new default filter.

static void IlvFileBrowser::SetInitOption

(

IlvFileBrowserOption

option

)

[static]

Overrides the resources or environment variables set for the current program.

Parameters:

option

The new option.

See also:

GetInitOption

void IlvFileBrowser::setOption

(

IlvFileBrowserOption

option

)

Sets the current option.

Parameters:

option

The new option of the file browser.

See also:

IlvFileBrowserOption.

void IlvFileBrowser::setPathName

(

const char *

path

)

Sets the directory to be browsed and the default file name.

Parameters:

path

The path name.

IlInt IlvFileBrowser::setPatterns	(	IlInt	count,
		const char *const *	filters,
		const char *const *	messages
	)

Initializes the filters and the related messages.

Parameters:

	count	The number of elements in the filters and messages arrays.
	filters	An array of count strings representing the filters. The syntax of a filter is shown in the following code: (filter1|filter2|....|filetern). For example, you can provide the string (*.ilv|*.iva).
	messages	An array of count strings representing the messages that describe the filters.

Returns:

count.

void IlvFileBrowser::setTitle

(

const char *

title

)

Sets the title of the dialog.

Parameters:

title

The new title.

See also:

getTitle

void IlvFileBrowser::setType

(

IlvFileSelectorType

t

)

Specifies whether this file browser must find a file that already exists.

For more information, see IlvFileSelector::setType.

virtual void IlvFileBrowser::show

(

)

[virtual]

Displays the file browser as a modal dialog.

As a result of this the member functions getFileName, getPathName, and getDirectory are able to return the correct value.

See also:

getFileName, getPathName, getDirectory