Rogue Wave Views
Gadgets Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Static Public Member Functions
IlvFileBrowser Class Reference

Dialog class. More...

#include <ilviews/gadgets/fbrowser.h>

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. More...
 
void ensureInScreen (IlvPos xMargin=0, IlvPos yMargin=0)
 Ensures that the file browser remains visible. More...
 
const char * get ()
 Displays the file browser as a modal dialog and returns a string. More...
 
const char * getDirectory () const
 Returns the directory part of the selected path. More...
 
IlvDisplaygetDisplay () const
 Returns the display used to create the file browser. More...
 
const char * getFileName () const
 Returns the file name part of the selected path. More...
 
IlInt getIndex () const
 Returns the index of the default filter and the corresponding message. More...
 
IlInt getIndexFromFilter (const char *filter) const
 Returns the index of a given filter. More...
 
IlInt getIndexFromMessage (const char *message) const
 Returns the index of a given message. More...
 
IlvFileBrowserOption getOption () const
 Returns the current option. More...
 
const char * getPathName () const
 Returns the full name of the selected path. More...
 
const char * getTitle () const
 Returns the title of the dialog. More...
 
IlvFileSelectorType getType () const
 Returns the current type of the dialog. More...
 
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. More...
 
void moveToScreen (IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue)
 Moves the file browser relative to the root window. More...
 
void moveToView (IlvView *view, IlvDirection justification=IlvCenter, IlvPos dx=0, IlvPos dy=0, IlBoolean ensureInScreen=IlTrue)
 Moves the file browser relative to another view. More...
 
void setDirectory (const char *dir)
 Sets the directory to be browsed. More...
 
void setFileName (const char *filename)
 Sets the default file name. More...
 
void setIndex (IlInt index)
 Sets the index of the default filter and the corresponding message. More...
 
void setOption (IlvFileBrowserOption option)
 Sets the current option. More...
 
void setPathName (const char *path)
 Sets the directory to be browsed and the default file name. More...
 
IlInt setPatterns (IlInt count, const char *const *filters, const char *const *messages)
 Initializes the filters and the related messages. More...
 
void setSortMode (IlPathName::SortMode mode)
 Sets the sort method for entries in the file browser. More...
 
void setTitle (const char *title)
 Sets the title of the dialog. More...
 
void setType (IlvFileSelectorType t)
 Specifies whether this file browser must find a file that already exists. More...
 
virtual void show ()
 Displays the file browser as a modal dialog. More...
 

Static Public Member Functions

static IlvFileBrowserOption GetInitOption ()
 Returns the value read from the resources or environment variables, or the value overridden by SetInitOption(). More...
 
static void SetInitOption (IlvFileBrowserOption option)
 Overrides the resources or environment variables set for the current program. More...
 

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
displayThe connection to the display.
transientForThe system view for which the dialog is transient (see IlvView).
dirThe directory to be browsed.
nbThe numbers of filters and related messages specified by the filters and messages parameters, respectively.
filtersAn array of strings representing the possible filters.
messagesAn array of strings representing the messages that describe the filters.
useSystemDlgA 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
xMarginThe horizontal margin.
yMarginThe 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
filterThe 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
messageThe 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
justificationSpecifies 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;
dxThe horizontal offset that is applied.
dyThe vertical offset that is applied.
ensureInScreenIf 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
justificationSpecifies 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.
dxThe horizontal offset that is applied.
dyThe vertical offset that is applied.
ensureInScreenIf 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
viewThe reference view.
justificationSpecifies 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.
dxThe horizontal offset that is applied.
dyThe vertical offset that is applied.
ensureInScreenIf 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
dirThe directory to be browsed.
void IlvFileBrowser::setFileName ( const char *  filename)

Sets the default file name.

Parameters
filenameThe default file name.
void IlvFileBrowser::setIndex ( IlInt  index)

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

Parameters
indexThe 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
optionThe new option.
See also
GetInitOption().
void IlvFileBrowser::setOption ( IlvFileBrowserOption  option)

Sets the current option.

Parameters
optionThe 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
pathThe path name.
IlInt IlvFileBrowser::setPatterns ( IlInt  count,
const char *const *  filters,
const char *const *  messages 
)

Initializes the filters and the related messages.

Parameters
countThe number of elements in the filters and messages arrays.
filtersAn 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).
messagesAn array of count strings representing the messages that describe the filters.
Returns
count.
void IlvFileBrowser::setSortMode ( IlPathName::SortMode  mode)

Sets the sort method for entries in the file browser.

Note that this method is only effective if this file browser is not using the system file selector.

Specifies how file and directory names are sorted in the file chooser. The sort mode can be any combinaison of the values of the IlPathName::SortMode enumeration.

If IlPathName::GroupDirectories is specified, files are listed after the directories.

Parameters
modeThe sort method that must be used.
void IlvFileBrowser::setTitle ( const char *  title)

Sets the title of the dialog.

Parameters
titleThe 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()

© Copyright 2016, 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.