IlvFileSelector Class Reference

File selector system dialog. More...

#include <ilviews/util/dialogs.h>

Public Member Functions
	IlvFileSelector (IlvSystemView parent, const char *message, const char *directory=0, const char *pattern=0)
	Constructor. More...
	~IlvFileSelector ()
	Destructor. More...
void	setFilter (const char *filter)
	Changes the file name filter. More...
void	setInitValue (const char *fileName)
	Initializes the path of the dialog box. More...
void	setMessage (const char *message)
	Change the dialog box message. More...
void	setTitle (const char *title)
	Sets the dialog's title. More...
void	setType (IlvFileSelectorType type)
	Sets the type of this file selector. More...
const char *	show (const char *directory=0, const char *pattern=0)
	Displays the dialog box. More...
const char *	show (IlvPos x, IlvPos y, const char *directory=0, const char *pattern=0)
	Displays the dialog at a given location. More...
const char *	showToMouse (IlvDisplay *display, IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue, const char *initialDirectory=0, const char *filePattern=0)
	This function shows the dialog at a position relative to the position of the mouse pointer. More...
const char *	showToScreen (IlvDisplay *display, IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue, const char *initialDirectory=0, const char *filePattern=0)
	This function shows the dialog at a position relative to the working space screen. More...
const char *	showToView (const IlvView *view, IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue, const char *initialDirectory=0, const char *filePattern=0)
	This function shows the dialog at a position relative to the position of the view given as parameter. More...

Static Public Member Functions
static IlBoolean	IsImplemented ()
	Queries the usability of this class. More...

Detailed Description

File selector system dialog.

Library: xviews or winviews or mviews (mutually exclusive)

This class builds a dialog box that asks the user to specify a path name.

- An IlvFileSelector on a Windows platform -

This class is dependent on the standard toolkit used in conjunction with Rogue Wave Views. It can be used only if you link your final application with the system toolkit supported by Rogue Wave Views (on Unix platforms, you must use the library libmviews instead of libxviews and link with the Motif library). If you do not want to use these libraries, you can use IlvIFileSelector; this class is based on Rogue Wave Views gadgets only and does not depend on the system toolkit.

See also

IlvIFileSelector.

Constructor & Destructor Documentation

IlvFileSelector()

IlvFileSelector::IlvFileSelector	(	IlvSystemView	parent,
		const char *	message,
		const char *	directory = 0,
		const char *	pattern = 0
	)

Constructor.

Parameters

parent	The system view (that you usually get by calling the method IlvAbstractView::getSystemView of an existing view) for which this dialog is created. The dialog, when displayed, is transient for this view.
message	The message that is displayed in the dialog. Note that the Windows file selector does not have any predefined area where to place a message, so message is used as the initial title of the dialog.
directory	The initial directory where the user will start to browse.
pattern	A pattern (or filter) such as "*.cpp" that is used by the dialog box when showing the file names in a directory.

~IlvFileSelector()

IlvFileSelector::~IlvFileSelector

(

)

Destructor.

The encapsulated widget is destroyed.

Member Function Documentation

IsImplemented()

static IlBoolean IlvFileSelector::IsImplemented ( )

static

Queries the usability of this class.

Returns

IlTrue if you can use this class in your application. Typically, this indicates that you are running on Windows, or that you have linked properly with a graphic toolkit on top of X Window that supports this dialog box.

setFilter()

void IlvFileSelector::setFilter

(

const char *

filter

)

Changes the file name filter.

Parameters

filter

The new filter that must be used. The string is copied.

setInitValue()

void IlvFileSelector::setInitValue

(

const char *

fileName

)

Initializes the path of the dialog box.

Parameters

fileName

The path and name of the file where the file browser will start the next time show() is called. The string is copied.

setMessage()

void IlvFileSelector::setMessage

(

const char *

message

)

Change the dialog box message.

Because the Windows file selector dialog box does not have a message area, this method has a specific behavior on this platform: the message that you pass is used in the "Files of type:" field, so that you can have a clear message that corresponds to the filter that you have set (such as in the image above, the filter is set to ".ilv" and the message is set to something that explains what this filter refers to. If you want to set a real message, you must use setTitle instead.

Parameters

message

The new message displayed next to the file selection areas. This string is copied.

setTitle()

void IlvFileSelector::setTitle

(

const char *

title

)

Sets the dialog's title.

The default title is "File Selector" (except on Windows where you indicate the title of this dialog box in the constructor). Use this method to change this to whatever you need.

Parameters

title

The new title of this dialog. The string is copied.

setType()

void IlvFileSelector::setType

(

IlvFileSelectorType

type

)

Sets the type of this file selector.

Parameters

type	The type of the selection box.

show() [1/2]

const char* IlvFileSelector::show	(	const char *	directory = 0,
		const char *	pattern = 0
	)

Displays the dialog box.

Pops the dialog box on the screen, and waits until the user has chosen a file name and pressed the OK or Cancel buttons.

Parameters

directory	The directory where the file chooser starts. If you set this parameter to 0 or leave this unspecified, the browsing starts in the directory where the last selection was stopped.
pattern	The pattern that must be used to select the file names. If you set this parameter to 0 or leave this unspecified, the filter is the last used filter.

Returns

The absolute file name that was chosen, or 0 if the user has pressed the Cancel button. The returned string must not be modified or deleted.

show() [2/2]

const char* IlvFileSelector::show	(	IlvPos	x,
		IlvPos	y,
		const char *	directory = 0,
		const char *	pattern = 0
	)

Displays the dialog at a given location.

This member function is similar to show(), but you can specify the location of the dialog box.

Parameters

x	The x coordinate, relative to the upper-left corner of the screen, where the dialogs appears.
y	The y coordinate, relative to the upper-left corner of the screen, where the dialogs appears.
directory	The directory where the file chooser starts. If you set this parameter to 0 or leave this unspecified, the browsing starts in the directory where the last selection was stopped.
pattern	The pattern that must be used to select the file names. If you set this parameter to 0 or leave this unspecified, the filter is the last used filter.

Returns

The absolute file name that was chosen, or 0 if the user has pressed the Cancel button. The returned string must not be modified or deleted.

showToMouse()

const char* IlvFileSelector::showToMouse	(	IlvDisplay *	display,
		IlvDirection	justification = IlvCenter,
		IlvPos	dx = 0,
		IlvPos	dy = 0,
		IlBoolean	ensureInScreen = IlTrue,
		const char *	initialDirectory = 0,
		const char *	filePattern = 0
	)

This function shows the dialog at a position relative to the position of the mouse pointer.

This function is similar to the function IlvView::moveToMouse, except that it shows the dialog and returns the value chosen by the user.

The dialog is shown at the position indicated by the position of the pointing device, with an offset of dx and dy.

The parameter justification specifies the point in the dialog that must be shown at the mouse location:

• IlvCenter: The center of the dialog.
• IlvTop: The middle of the top side of the dialog.
• IlvBottom: The middle of the bottom of the dialog.
• IlvLeft: The middle of the left side of the dialog.
• IlvRight: The middle of the right side of the dialog.
• IlvTopLeft: The top left corner of the dialog.
• IlvTopRight: The top right corner of the dialog.
• IlvBottomLeft: The bottom left corner of the dialog.
• IlvBottomRight: The bottom right corner of the dialog.

Parameters

display	A const pointer to an IlvDisplay.
justification	An IlvDirection that gives how the position must be computed relative to the view.
dx	An IlvPos that gives the offset for the abscissa.
dy	An IlvPos that gives the offset for the ordinate.
ensureInScreen	An IlBoolean that indicates whether the dialog must be thoroughly inside the working space of the screen (if possible).
initialDirectory	A const pointer to a C-style string that is the value to initialize the directory for the files to be listed in the dialog.
filePattern	A const pointer to a C-style string that is the value of a filter for the files to be listed in the dialog.

Returns

A const pointer to a C-style string. This is either a null pointer when the user closes the dialog by clicking on Cancel or a pointer to a string that contains the path name chosen by the user. This string is valid as long as the dialog is valid and one of the show methods was not called.

showToScreen()

const char* IlvFileSelector::showToScreen	(	IlvDisplay *	display,
		IlvDirection	justification = IlvCenter,
		IlvPos	dx = 0,
		IlvPos	dy = 0,
		IlBoolean	ensureInScreen = IlTrue,
		const char *	initialDirectory = 0,
		const char *	filePattern = 0
	)

This function shows the dialog at a position relative to the working space screen.

This function is similar to the function IlvView::moveToScreen, except that it shows the dialog and returns the value chosen by the user.

The dialog is shown at the position indicated by justification, relative to the screen, with an offset of dx and dy.

Valid values for justification are:

• IlvCenter: The center of the dialog is at the center of the screen.
• IlvTop: The top side of the dialog is at the top of the screen.
• IlvBottom: The bottom side of the dialog is at the bottom of the screen.
• IlvLeft: The left side of the dialog is at the left of the screen.
• IlvRight: The right side of the dialog is at the right of the screen.
• IlvTopLeft: The top left corner of the dialog is at the top left of the screen.
• IlvTopRight: The top right corner of the dialog is at the top right of the screen.
• IlvBottomLeft: The bottom left corner of the dialog is at the bottom left of the screen.
• IlvBottomRight: The bottom right corner of the dialog is at the bottom right of the screen.

Parameters

display	A const pointer to an IlvDisplay.
justification	An IlvDirection that gives how the position must be computed relative to the view.
dx	An IlvPos that gives the offset for the abscissa.
dy	An IlvPos that gives the offset for the ordinate.
ensureInScreen	An IlBoolean that indicates whether the dialog must be thoroughly inside the working space of the screen (if possible).
initialDirectory	A const pointer to a C-style string that is the value to initialize the directory for the files to be listed in the dialog.
filePattern	A const pointer to a C-style string that is the value of a filter for the files to be listed in the dialog.

Returns

A const pointer to a C-style string. This is either a null pointer when the user closes the dialog by clicking on Cancel or a pointer to a string that contains the path name chosen by the user. This string is valid as long as the dialog is valid and one of the show methods was not called.

showToView()

const char* IlvFileSelector::showToView	(	const IlvView *	view,
		IlvDirection	justification = IlvCenter,
		IlvPos	dx = 0,
		IlvPos	dy = 0,
		IlBoolean	ensureInScreen = IlTrue,
		const char *	initialDirectory = 0,
		const char *	filePattern = 0
	)

This function shows the dialog at a position relative to the position of the view given as parameter.

This function is similar to the function IlvView::moveToView, except that it shows the dialog and returns the value chosen by the user.

The dialog is shown at the position indicated by justification, relative to the position and size of view, that must be a top view, with an offset of dx and dy. These offsets are relative to view. This means, for example, that when the dialog is justified with IlvLeft, the offset dx will be subtracted from the abscissa, and when the dialog is justified with IlvRight, the offset dx will be added to the abscissa. The principle is the same for the offset dy.

Valid values for justification are:

• IlvCenter: The center of the dialog is at the center of view.
• IlvTop: The bottom of the dialog is at the top of view.
• IlvBottom: The top of the dialog is at the bottom of view.
• IlvLeft: The right side of the dialog is at the left side of view.
• IlvRight: The left side of the dialog is at the right side of view.
• IlvTopLeft: The bottom right corner of the dialog is at the top left corner of view.
• IlvTopRight: The bottom left corner of the dialog is at the top right corner of view.
• IlvBottomLeft: The top right corner of the dialog is at the bottom left corner of view.
• IlvBottomRight: The top left corner of the dialog is at the bottom right corner of view.

Parameters

view	A const pointer to an IlvView. This parameter references the view from which the position is computed.
justification	An IlvDirection that gives how the position must be computed relative to the view.
dx	An IlvPos that gives the offset for the abscissa.
dy	An IlvPos that gives the offset for the ordinate.
ensureInScreen	An IlBoolean that indicates whether the dialog must be thoroughly inside the working space of the screen (if possible).
initialDirectory	A const pointer to a C-style string that is the value to initialize the directory for the files to be listed in the dialog.
filePattern	A const pointer to a C-style string that is the value of a filter for the files to be listed in the dialog.

Returns

A const pointer to a C-style string. This is either a null pointer when the user closes the dialog by clicking on Cancel, or a pointer to a string that contains the path name chosen by the user. This string is valid as long as the dialog is valid and one of the show methods was not called.