.. highlightlang:: us

.. index:: GetSaveFileName

.. _getsavefilename:

GetSaveFileName
===============

.. us.tag  GetSaveFileName ENGLISH FILE_MISC DialogBoxes

:ref:`GetSaveFileName` opens a dialog box to select a file name.

.. function::  ssFilename = GetSaveFileName()
    ssFilename = GetSaveFileName(ssDir)
    ssFilename = GetSaveFileName(ssDir, ssFilter)
    ssFilename = GetSaveFileName(ssDir, ssFilter, nFilterIndex)
    ssFilename = GetSaveFileName(ssDir, ssFilter, nFilterIndex, ssTitle)
    <ssFilename, nFilter> = GetSaveFileName()
    <ssFilename, nFilter> = GetSaveFileName(ssDir)
    <ssFilename, nFilter> = GetSaveFileName(ssDir, ssFilter)
    <ssFilename, nFilter> = GetSaveFileName(ssDir, ssFilter, nFilterIndex)
    <ssFilename, nFilter> = GetSaveFileName(ssDir, ssFilter, nFilterIndex, ssTitle)

.. us.return

**Return Value**

The function returns a scalar string containing the complete file name
(*ssFileName*). If the user chose the **Cancel** button, the function returns
an empty string (``""``).

.. us.params

**Parameters**

.. uparam:: ssDir

   The parameter *ssDir* contains a path name. Example
   :file:`c:/Program/UniPlot/Samples`. If *ssDir* is a complete file name the
   file name is used to initialize the File Name edit control.

.. uparam:: ssFilter

   *ssFilter* The filter string *ssFilter* contains one or more strings for the
   file format combo box. The filter string has the following structure: 
   ``"All files (*.*)|*.*|"``
   More than one filter can be specified. Example:
   ``"Text File (*.txt)|*.txt|All Files (*.*)|*.*|"``

.. uparam:: nFilterIndex

   This parameter specifies which filter is selected when the dialog box is
   displayed on the monitor. Filter enumeration starts with 1.

.. uparam:: ssTitle

   Title of the dialog box.

.. us.example

**Example**

::

   * GetSaveFileName();
   d:/data/test.dat
   * GetSaveFileName("c:", ..
         "UniScript Files (*.ic)|*.ic|" + ..
         "All Files (*.*)|*.*|").

.. seealso::
   :ref:`overview-files`,
   :ref:`GetOpenFileName`,
   :ref:`DialogBox`,
   :ref:`MessageBox`

:sub:`id-1115219`