Rogue Wave Views
Foundation Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Static Public Member Functions
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)
 Initializes a new IlvFileSelector instance. 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)
 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)
 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)
 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 
)

Initializes a new IlvFileSelector instance.

Parameters
parentThe 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.
messageThe 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.
directoryThe initial directory where the user will start to browse.
patternA 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
filterThe 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
fileNameThe 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
messageThe 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
titleThe new title of this dialog. The string is copied.

§ setType()

void IlvFileSelector::setType ( IlvFileSelectorType  type)

Sets the type of this file selector.

Parameters
typeThe 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
directoryThe 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.
patternThe 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
xThe x coordinate, relative to the upper-left corner of the screen, where the dialogs appears.
yThe y coordinate, relative to the upper-left corner of the screen, where the dialogs appears.
directoryThe 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.
patternThe 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 
)

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
displayThe display instance that is used.
justificationIndicates how the position must be computed relative to the view.
dxThe offset for the abscissa.
dyThe offset for the ordinate.
ensureInScreenIndicates whether the dialog must be thoroughly inside the working space of the screen (if possible).
initialDirectoryThe value to initialize the directory for the files to be listed in the dialog.
filePatternThe value of a filter for the files to be listed in the dialog.
Returns
0 if the user closes the dialog by clicking on the Cancel button, 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 
)

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
displayThe display instance that is used.
justificationIndicates how the position must be computed relative to the view.
dxThe offset for the abscissa.
dyThe offset for the ordinate.
ensureInScreenIndicates whether the dialog must be thoroughly inside the working space of the screen (if possible).
initialDirectoryThe value to initialize the directory for the files to be listed in the dialog.
filePatternThe value of a filter for the files to be listed in the dialog.
Returns
0 if the user closes the dialog by clicking on the Cancel button, 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 
)

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
viewThe view from which the position is computed.
justificationAn IlvDirection that gives how the position must be computed relative to the view.
dxThe offset for the abscissa.
dyThe offset for the ordinate.
ensureInScreenIndicates whether the dialog must be thoroughly inside the working space of the screen (if possible).
initialDirectoryThe value to initialize the directory for the files to be listed in the dialog.
filePatternThe value of a filter for the files to be listed in the dialog.
Returns
0 if the user closes the dialog by clicking on the Cancel button, 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.

© Copyright 2018, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.